
Pur pose and Overview 



The qrophics capabilities of GraFORTH can be divided into three 
main qroups: 

Two-Dimensional Graphics (or "Graphics of the Fij^t K/""") 
includes commands that plot points, draw lines, and fi 1 
rectangular areas on the screen, usinc, a variety of colors and 
opt i ons . 

Character Graphics (or "Graphics of the Second Kind") includes 
usum and creating new character sets, displaying text with 

erent sUes and colors, and defining completely new shapes 
,nd pictures in terms of character sets and displaying these 
shapes using a special block printing function. 

Three-Dimensional Graphics (or "Graphics of the Third Kind") 
IrcTudes creating and displaying three-dimensional color images 
at high speed for animated effects. 

This chapter will discuss two-dimensional graphics. We'll start 
by talking about what the Apple itself is capable of. and how 

raFORTH uses these capabilities. WeM show you ^^"w/" ° 
points and draw lines, and then undraw them again, effectively 

n them from the screen. We'll discuss co or and the 
drawing modes (ORMODE and EXMOOE and how they affect the 

raw 3 P oces . We'll also talk about usi ng Turt legraphi cs , 
Sch is especially useful for creating certain kinds of 
graphics displays. 
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Apple Graphics 



The Apple screen display, whether it be text or graphics, is 
;i)ade out of the same units, called pixels. A pixel (abbreviated 
form of 'picture cell') is the smallest unit, or dot, which may 
be turned on or off of the surface or the screen. There are 
53,7fin of these smallest units which make up the entire screen, 
arranged in a matrix 280 dots wide and 192 dots high. 

The standard Apple text display divides the screen into 24 
horizontal lines, each fi dots high. Seven of these B vertical 
dots are used to form the characters, while the eighth is used 
to separate the lines from one another. Horizontally, the 
screen is divided into 40 columns, each 7 dots wide. Five of 
these 7 horizontal dots are used to form the character, while 
one on each side of the character is used for spacing between 
the characters. The ASCII values for the characters on the text 
screen are stored in a 1024 byte memory area. The hardware 
inside the Apple continuously reads the values from this area 
and places the appropriate characters on the screen. 

The Apple graphics display allows you to turn on or off all 
S3, 760 dots on the screen individually. There are two 'graphics 
pages' in memory reserved for this function, but because of the 
higher resolution, each requires 8192 bytes to be set aside. It 
is possible to alternate between the pages very rapidly for 
animation effects (GraFORTH does this automatically for 3-0 
displays), but the Apple display hardware cannot merge or blend 
the information on the two pages. These two high resolution 
pages are often called 'picture buffers'. Each dot on the 
screen represents one bit from the picture buffer. Seven of the 
8 bits in each byte are displayed on the screen, with the last 
bit used in determining the colors of the other dots in that 
byte. 
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GraFORTH Graphics 



While It is possible to use the Apple text display from GraFORTH 
(with the word TEXT), the usual display is the graphics display. 
To specify points on the qraphics screen, RrdTORTH uses 
'Cartesian coordinates'. This is a straightforward way to 
select a point by namini) the column and the row the point is in. 
The horizontal position is the X coordinate and the vertical 
position is the Y coordinate. 

The range of screen coordinates for GraFORTH graphics is: 

X froiri (screen left) to (screen riqht) 

Y from (screen top) to 191 (screen bottom) 

Thus, the upper-left corner of the screen can be represented 
with'x=0 and Y=0, or simply the X-Y pair (0,0). 

Mote: The GraFORTH graphics screen is 9 percent narrower than 
the maximum possible (256 points wide rather than 280) for the 
sake of operating speed. This is one factor that contributes to 
GraFORTH 's fast line drawing. 

The standard Apple text display still uses all 280 dots across 
the screen for 40 characters per line. The characters 
themselves, instead of being placed on a text screen by the 
Apple hardware, are "drawn" from the text page onto the graphics 
picture buffer. The full character space, 7 dots by 8 dots, can 
be used, and is used for lower case characters and special 
character styles. 

Two-Dimensional Graphics Words 



PLOT, LINE and FILL 

For these examples, we don't want text scrolling all over our 
beautiful graphics, so let's establish a text window in the 
bottom part of the screen. These examples will keep the 
graphics above the text window and away from harm. To establish 
the window, type: 

Ready 40 18 24 WINDOW 
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This sets a 4n-column wide window frcm line 18 to the bottom of 
the screen. Now type: 

Ready ERASE 

Tnis clears the text that was still ibove the text window. 

Let's begin at the beginning, with plotting points. The 
GraFORTH word PLOT removes two numbers from the stack, 
interprets them as X and Y coordinatis, and plots a point at 
those coordinates on the screen. Th; form for PLOT is: 

<X-coordindte> <Y-coordi nate> PLOT 

This example will plot a point in ths upper left corner of the 
screen : 

Ready PLOT 

Here is another point, in the upper right portisn of the screen: 
Ready 200 25 PLOT 

The word LINE, like PLOT, removes two numbers from the stack and 
interprets them as X and Y coordinates. LINE t>en draws a 
straight line from the last plotted point to thf given 
coordinates. To draw a line, we use the last pilnt we plotted 
as one of the endpoints. We simply give LINE tie coordinates of 
the other endpoint: 

Ready 50 100 LINE 

This draws a diagonal line from the point (200, ?5) to (50,100). 
We can draw another line, by using PLOT and LINI together again: 

Ready 100 10 PLOT 100 140 LINE 

This draws a vertical line through the other line and almost 
into our text window. 

Rectangular areas can be filled in ([uickly with the word FILL. 
FILL also removes X and Y coordinates from the stack. It treats 
the last plotted point as one corner of the area, and the given 
coordinates as the opposite corner. This example fills in a 
rectangular area on the right side if the screen: 
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Ready l?n 125 PLOT 



Ready 200 75 FILL 

l-or both LINE and FILL, the "last plotted point" is always the 
point last used by a plottinq word, whether it was PLOT, LINE, 
or FILL. Another word, POSN, removes X and Y coordinates from 
the stack to act as a "last plotted point" without doing any 
plotting. POSN can be used to determine the first endpoint of a 
line or one corner of an area. This example uses POSN to set the 
first endpoint of a line: 

Ready 225 50 POSN 

Ready 250 125 LINE 

COLOR 

Of course, GraFORTH can draw in colors, too! The color is set 
with the word COLOR. COLOR removes a number from the stack and 
uses it to select a color. The eight color numbers (0 through 
7) are the same as those used by Applesoft Basic. Here is a 
listing of the graphics colors: 



C olor N ainber Color 

not used 

1 Green (1) 

2 Violet (1) 

3 White (1) 
(1 not used 

5 Orange (?) (depends on monitor) 

6 Blue (2) (depends on monitor) 

7 White (2) 



The orange and blue colors may appear different shades on 
different color monitors. The colors can be divided into two 
groups. The numbers in parentheses represent the "group number" 
(either 1 or 2). Because of some Apple ][ hardware constraints, 
it may be desirable to use colors from the same group when 
drawing lines or areas close together. We'll show you an 
e;(ample of this in a bit. (The Apple ][ Reference Manual 
contains more information on the internal details of these 
constraints. ) 

If you don't mind a bit of typing, this example will display 6 
diagonal lines in each of the visible colors: 
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Ready ERASE 

Ready 1 COLOR PLOT 1100 100 LINE 
Ready 2 COLOR 20 PLOT r 120 100 LINE 
Ready 3 COLOR 40 PLOT f 140 100 LINE 
Ready 5 COLOR 60 PLOT T 160 100 LINE 
Ready 7 COLOR 100 PLODT 200 100 LINE 

With your color monitor' properly adjusted, the colors of these 
lines (from left to riglght) should be green, violet, white, 
orange, blue, and anothaer brand of white. Note that the colored 
lines are not broken att all, as they are with some graphics 
displays (like Applesofft). GraFORTH draws all colored lines 
without breaks. 

Lines and points can bee drawn over FILLed areas, but the colors 
will be affected: 

Ready ERASE 

Ready 5 COLOR 

Ready PLOT 100 100 I FILL 

This draws an orange reectangle in the upper left portion of the 
screen. Now let's draww a line of a different color through it: 

Ready 6 COLOR 

Ready PLOT 100 100 I LINE 

Note that 6 COLOR speciifies blue, but because of the orange 
background, the line apppears white. Now let's try the same 
example again, this timme using colors from different color 
groups : 

Ready ERASE 5 COLOR 

Ready PLOT 100 100 FILL 

Ready 1 COLOR 

Ready PLOT 100 100 i LINE 
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Whoops! You sfioulfl see d series of small iinjen rectanqles alomi 
tlie diaqonal. This is the result of the Apple ][ hardwdre 
Hinitdtions. The solution to avoiding this trouble is to simply 
use colors of the same group when lines or areas are 
superimposed or placed close toqether. 

UN PLOT, UN LINE, and EMPTY 

So far we've been using the word ERASF to clear the graphics 
from the screen. In GraFORTH, points, lines, and areas can be 
selectively erased. Let's ERASE the entire screen now and set 
the color hack to white, then plot a few points: 

Ready E'(ASE 3 COLOR 

Ready 50 25 PLOT 

Ready 100 ?5 PLOT 

Ready 150 25 PLOT 

Points can be individually removed with the word UNPLOT. UNPLOT 
has the same form as PLOT, however it erases the point at the 
given coordinates. (If there is no point there to begin with, 
nothing happens.) Let's use UNPLOT to erase two of the points 
we have on the screen: 

Ready 50 25 UNPLOT 

Ready 100 25 UNPLOT 

Similarly, lines can be erased with the word ONLINE. This 
exdi;iple draws two lines, then erases one of them: 

Ready PLOT 100 100 LINE 

Ready 50 PLOT 150 100 LINE 

Ready UNPLOT 100 100 ONLINE 

Rectangular areas created with FILL can be erased with the word 
EMPTY. Here we'll FILL two areas, and erase one: 
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Ready 25 75 PLOT 100 126 FILL 



Ready 175 25 PLOT 225 100 FILL 
Ready 25 75 UNPLOT 100 125 EMPTY 

Points, lines, and areas must be UNdrawn using the same color 
they were drawn in. For example, all of the above objects were 
drawn with 3 COLOR set. The same color was still in effect when 
some of the objects were erased. Let's change the color and try 
erasing the remaining line and area: 

Ready 1 COLOR 

Ready 50 UNPLOT 150 100 UNLINE 

Since 1 COLOR is set, the GraFORTH system assumes a gree n line 
is to be erased, and leaves a string of violet dots behind. 

Ready 2 COLOR 

Ready 175 25 UNPLOT 225 100 EMPTY 

With 2 COLOR set, GraFORTH tries to erase a violet colored area, 
changing the white to green. 

INVERSE and NORMAL 

If you prefer to do graphics on a white background, you can do 
this with the word INVERSE. INVERSE simply draws the 
'complements' of the selected color: white becomes black, black 
becomes white, green becomes violet, blue becomes orange, etc. 
To show the effects of INVERSE, let's first erase the screen, 
then enter INVERSE: 

Ready ERASE 

Ready INVERSE 

Notice that the "Ready" on the last line is now displayed in 
"inverse": black characters on a white background. Since only 
the word "Ready" was printed after executing INVERSE, it is the 
only thing displayed in inverse. Now type: 
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Rc-ddy HOME 

Sincfl HOME clears the text wvindow, now everythinq inside the 
text window is in inverse. fNow tyne; 

Refidy ERASE 

hKASE has "erased" the entirfe screen to white. Let's draw the 
:i X colored 1 ines aqain: 

Reddy 1 COLOR PLOT 100 1100 LINE 

Ready ? COLOR 20 PLOT \?0 100 LINE 

Ready 3 COLOR 40 PLOT {'iO 100 LINE 

Ready 5 COLOR 50 PLOT 160 100 LINE 

Ready fi COLOR BO PLOT 180 100 LINE 

Ready / COLOR 100 PLOT 2003 100 LINE 

Note that the colors of the lines have all channed. From left 
to right, the colors are nowv violet, green, black, hlue, orange, 
and another black. 

We'll eventually want to retturn to a normal black-background 
display. The word NORMAL caauses GraFORTH to use the normal 
colors again, including goodd ol ' black: 

Ready NORMAL 

Ready ERASE 

ORMODE and EXMOLDE 

OraFORTH has two different "('drawing modes", called "ORMOOE" and 
"EXMODE". Amazingly enough,, these modes are set with the 
GraFORTH words ORMODE and EXKMOOE. The 'default' mode (the mode 
GraFORTH uses when a mode iss not specified) is ORMODE. The 
philosophy behind ORMODE is that the plotting words put dots of 
the specified color on the sscreen regardless of what is already 
on the screen. With EXMODE I however, a drawing command will put 
points on the screen only whlnere points are not already plotted. 
If soirie points to be plottedd are already plotted, those points 
will instead be turned off. 
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A couple of examples will be helpful here. Let's first FILL an 
area, then draw an overlapping line in ORMODE: 

Ready 100 50 POSN 150 100 FILL 

Ready 50 50 POSN 200 100 LINE 

The line goes straight through the middle of the rectangle. 
Watch what happens when we try to erase the Hine: 

Ready 50 50 POSN 200 100 ONLINE 

The line was erased, but it neatly chopped tihe rectangle in 

half, too. Using EXMODE, anything that can toe done can also be 

undone. Let's do the same example again, thiis time in EXMODE: 

Ready ERASE EXMODE 

Ready 100 50 POSN 150 100 FILL 

Ready 50 50 POSN 200 100 LINE 

The line is white, except where it passes over the white 
background of the rectangle. Here it is chamqed to black. Now 
to erase the line, we want to make the white sections black, and 
the black trace through the rectangle white. And this is 
exactly what happens with regular plotting im EXMODE. We can 
erase the line by telling GraFORTH to draw itt again: 

Ready 50 50 POSN 200 100 LINE 

The line is erased, and the rectangle is agaiin intact. The key 
to understanding EXMODE is that if something is drawn once, it 
appears on the screen. If it is drawn again,, it disappears, 
leaving the screen as if the object had never been drawn. 

EXMODE works equally well with colors. In thiis example, a green 
line is drawn through the rectangle, the whitte rectangle is 
erased, then the line is erased: 

Ready 1 COLOR 50 50 POSN 200 100 LINE 

Notice that the line is violet inside the rectangle. 

Ready 3 COLOR 100 50 POSN 150 100 FILL 



TWO DIMENSIONAL GRAPHICS 



6-11 



The line is now completely q-een. as if the rectanqle never 
exi sted. 

Ready 1 COLOR 50 50 POSN 200 100 LINE 

EXMODE and ORMOOE can be coiroined with INVERSE and NORMAL alonq 
with the six colors to prodice a wide variety of color and 
pattern combinations, more than we could hope to fully explore 
here. We suqqest that you e<periment further with these various 
comfji nations, to see how the/ can work best for your 
dppl i cat ions. 



GPEEK 

Your oroqrdins can determine whether or not a qiven point on the 
screen has been plotted wit! the word GREEK. GPEEK removes X 
and Y coordinates from the stack, looks to those coordinates on 
the screen, and places a nor zero number stack if the point 
there is "on" (not black) or a zero if the point is "off" 
(black). The following exanple draws a line, then checks two 
points, one on the line and one off: 

Ready 3 COLOR PLOT 100 00 LINE 

Ready 50 50 GPEEK . 
? 

Ready 200 10 GPEEK. 
U 



Turtlegraphics 

Turtleqraphics is also available from GraFORTH. Turtleqraphi cs 
IS a somewhat different way of specifying how to dr^aw Unes in 
GraFORTH. Imagine a tiny turtle sitting on the middle of the 
screen with ink on his tail. Wherever he moves he draws a line 
behind him. We can tell him to turn to the left or the right, 
and we can tell him to walk forward a qiven distance leaving a 
straight line behind him. (For the mathematicians among us, 
this way of drawing lines (Duld be considered as using relative 
pol ar coordi nates" . ) 

The Turtleqraphics words ir GraFORTH are found on the system 
disk in a text file cal led "TURTLE". We can compile these words 
into the dictionary by typing; 
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Ready READ " TURTLE " 



We can see the words added to the dictionary by typing LIST. A 
few of the words are used by the other words: TURTLE. X, 
TURTLE. y, and TURTLE. ANG are variables, and TURTLE. WALK is 
called by bc.h MOVE and MOVETO, 

Let's "initialize" Turtlegraphics by typing: 

Ready TUKTIE 

TURTLE resets graphics mode, erases the screen and sets a text 
window along the bottom four lines, then sets 3 COLOR (white) 
and positions the turtle in the center of the screen, facing 
toward the top. 

MOVE 

The word MOVE moves the turtle in the direction it Is pointing, 
drawing a line. The form is; 

<distance> MOVE 

The distance is measured in' pixels, or dots. To move the turtle 
50 pixels, type: 

Ready 50 MOVE 

TURNTO 

The turtle can be turned to a certain angle with TURNTO. TURNTO 
has the form; 

<angle> TURNTO 

The angle given is in degrees, and increasing angles are in a 
clockwise direction. Zero is straight up, 90 is to the right, 
180 is facing down, and 270 is to the left. Let's move the 
turtle in our example to face to the right (to 90 degrees), then 
move it 75 pixels: 

Ready 90 TURNTO 

Ready 75 MOVE 
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TURN 



The word TURN turns the turtle clockwise from its current 
direction a i^iven angle. The form is the same as for TURNTO, 
but TURN is a relative turn frotn the turtle's current direction. 
The following exairiple now turns the turtle 45 more degrees 
clockwise, then moves the turtle 5(1 pixels: 

Ready 45 TURN 

Heddy 50 MOVE 

MO VETO 

Lastly, MOVETO moves the turtle directly to a specified X,Y 
position on the screen without drawing any line. The form for 
MOVETO is: 

<X coordinate) <Y coordinate) MOVETO 

MOVETO is similar to POSN in that it simply establishes a new 
point on the screen, but f^OVETO also updates the turtle's 
position for further Turtlegraphics commands. We can move the 
turtle to the upper-left corner of the screen, turn it to face 
to the lower-right, then move it back to the center, drawing a 
line, with the following commands: 

Ceddy MOVETO 

Ready \21 TURNTO 

Ready 160 MOVE 

Examples 

The advantage of Turtlegraphics is that shapes can be drawn in 
different sizes and facing different directions with little 
work. For example, to draw a square, you can type the 

f ol 1 owi nq : 

Ready TURTLE 

Ready 50 MOVE 90 TURN 50 MOVE <30 TURN 
Ready 50 MOVE ^)0 TURN 50 MOVE 
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A faster way is to repeat the words in a loop: 
Read> TURTLE 

Ready 4 DO 50 MOVE 90 TURN LOOP 

This line can be put into a word definition and used at any 
time: 

: SQUARE 

4 no 

50 MOVE 
90 TURN 
LOOP ; 

Now the square can be drawn starting at any point on the screen 
and turned any direction: 

Ready TURTLE 

Ready 100 MOVETO SQUARE 
Ready 55 100 MOVETO 30 TURNTO SQUARE 
Ready 120 100 MOVETO 60 TURNTO SQUARE 
Ready 190 100 MOVETO 90 TURNTO SQUARE 



(Note: The GraFORTH word SIN is used to compute sines of angles 
used in Turtlegraphics. If you have an applications program that 
uses angles, the word SIN can be very helpful. SIN removes a 
number from the stack and uses it to select and return a scaled 
sine value. The table repeats for every 12fi numbers, and 
returned values range from -12R to 127.) 
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CHAPTER SEVEN: CHARACTER GRAPHICS 
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Purpose and Overview 



GrarORTH can do weird and wonderful thinqs with the characters 
ilisplayed on the screen. Text can be reverse scrolled, down the 
screen. Characters can he made much larqer, and di splayecT^fn 
color. Different character styles, or 'fonts' can be selected 
and even created in GraFORTH. Entire images can be defined 
within a character font and rapi'ily printed as a block of 
"characters" for animated displays. 

In this chapter we'll show you how to make use of each of these 
features and give you some suggestions for incorporating them 
into your own programs. 

Special Output Characters 

liesides the special input characters (ConTRoL-I, ConTRoL-0, etc.) 
discussed in Chapter 4, firaFORTM also uses two special output 
characters, ConTRoL-L, and ConTRoL-K. These characters are 
usua'ly printed from within a program, instead of entered at the 
krryboard. (They can be typed from the keyboard, but GraFORTH 
wi i ! try to read them as characters in a GraFORTH word.) 

CnniRoL-L (Apple ASCII number 140) erases the screen inside the 
text window. Printing a ConTRoL-L is equivalent to executing the 
word HOME. 

ConlRoL-K (Apple ASCII number 139) causes a reverse line feed, so 
that subsequent printing will be one line higher. If printing is 
already on the top line of the text window (the vertical tab 
ei|uals the top window margin), then the display will scroll in 
reverse, moving text down the screen. 
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Changing Character Size and Color 



GraFORTH has the unique ability to print characters in 8 
different sizes using the word CHRSIZE. CHRSIZE removes a number 
from the stack to select the character size. Valid numbers are 
from to 8, Character size specifies the usual GraFORTH 
character display. Character sizes 1 through R cause the 
characters to be "drawn" onto the screen using GraFORTH's color 
graphics capabilities. Character size 1 is the same size as 
character size 0, and the others are 2 through 8 times larger. 

Let's introduce some of these features through examples. First, 
we'll set everything back to normal by typing: 

Ready ABORT 

Now let's erase the normal sized characters from the screen and 
select a larger character size: 

Ready HOME 2 CHRSIZE 

(Erasing the screen with HOME is a normal but not required step 
in changing character size. If HOME is not used before changing 
size, in some cases not all entered characters will be printed.) 

The "Ready" prompt is now twice its normal size! You will notice 
that the large character sizes take a longer time to print, and 
that if allowed, scrolling is much slower than it is when using 
the standard character size. Also, the screen is actually 9X 
narrower than the standard size, since the graphics features are 
used to print them. 

The large characters can also be displayed in color! Type: 
Ready HOME 1 COLOR 

This will clear the screen, then make the text green. We cleared 
the screen again because combining two colors of text on the 
screen can have some unusual effects of its own. To see these 
effects, type: 
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Reddy 2 COLOR 

Now hit the <return> key a few times to cause the text to scroll. 
The "Ready" prompt that was qreen qets overwritten with the 
violpt but does not scroll. Only text of the current color and 
of the'current size will behave as expected with text commands. 

Obviously, when the characters are larqer. fewer characters can 
he displayed on the screen. When you select a new character size 
with CHRSIZE. firaFORTH automatically sets the text window size to 
the correct limits, to keep the text on the screen. Below is a 
I. Die relating character sizes to the number of charac1.ers that 
can he displayed, and indicatinq whether or not colored text is 
pubsible for that character size: 

Size Columns R ows Color? 
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YOU miqht want to try the followinq to see GraFORTH's larqest 
Character size in color. First type ABORT to qet yourself back 
to a predictable place, then type: 

Keady HOME 8 CHRSIZE 5 COLOR 

A m.inmoth oranqe "Ready" prompt will appear, split across two 
nnirs— wTth d huqe lumberinq cursor! Allowing time for the text 
to scrol 1 , now enter: 

i(e<i<iy INVERSE 

Afier another scroll, the display changes to Inverse. Obviously, 
you wouldn't want to enter a long program this way! Large 
Character sizes work very well for program or game displays hut 
weren't really intended to be used for input. The fastest way 
out of our current situation (besides hitting <reset>) is to 
type: 



CHARACTER GRAPHICS 



7 - 4 



Ready ABORT 



After the text scrolls once more, the ABORT is executed, and 
things are back to normal. 

Font Selection 



The character "style" used in a text display (the actual set of 
shapes of the characters displayed) is called a character 'font', 
or character set. The Apple ][ contains an uppercase-only 
character set stored in its hardware. GraFORTH uses this when 
TEXT mode is selected. However, GraFORTH's usual graphics 
display instead uses a character set from memory. This character 
set 1s stored in a binary file on the GraFORTH system diskette, 
and 1s read into memory when GraFORTH is first booted. 

The disk actually contains several character sets, and any of 
them can be used for text display. The character set files on 
disk are: 

CHR.SYS 
CHR.STOP 
CHR. SLANT 
CriR. GOTHIC 
CHR. BYTE 
CHR. STUFF 
CHR. MAXWELL 

(The last two are special character sets used for 'character 
graphics', and do not work well for a text display. We'll show 
you how to work with these in a bit...) 

In memory, a character set occupies 768 bytes. There are 96 
printable characters, and each character uses 8 bytes in the 
character set. These 8-byte blocks are actually graphics 
"pictures" of each character. When GraFORTH is booted, it loads 
CHR.SYS into memory starting at location 2048. Whenever it 
displays a character, it looks up the "picture" of that character 
from this area of memory, and places 1t on the screen. 

Character sets elsewhere in memory can also be used for the 

screen display. Let's load another character set from disk into 

a free area of memory. The location 2816 is the beginning of a 

large free area of memory. We'll use a standard DOS call to load 
the file in: 
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l(,.a,lv C« 13? PUTC PRINT " RLOAO CHU . B YTF , A?8 1 6 " CR 



U,e disk whirs a hit, and the character set is loaded. To use 
this character set for the display, the word CHRAUR is used. 
niuAUR stands for CHARacter AOdRess , and it is used to select the 
ineuiory location of the current character set. The form is: 

C.iddress of character set> CHRADR 

W.f loaded the character set into memory starting at location 
■/r'Af,, SO this is the address we qive to CHRADR: 

Keady I'Hlo CHKADR 

All pnntinq will now use the new character set. The characters 
thit wi-re already on the screen in the old character set, 
■ lo-evr are unchdn<ied. Characters from different character sets 
cdP he displayed on the screen at the same time. However, if the 
screen is scrolled, these characters will be reprinted a line 
hiqh'^r. using the newest character set. 

Tne AiCIl numbers for the printing characters range from KiO to 
To display all of the printing characters in the set at 

once using I".ITC, type: 

Ready 266 160 DO I PUTC LOOP 

Vuu may want to load the other character sets into memory to see 
what the/ look like. You can load them into the same area of 
memory and overwrite CHR.BYTE, or you can use another free area 
.,t memory and select it with CHRADR. The memory map in Appendix 

shows the free areas of memory. Therefore, it is possible (and 
,.,isy i) to have several character sets in memory at once, quickly 
.Hanging from one to another. Care should be taken, however, to 
jvuid overwriting a portion of the GraFORTH system. Remember 
mat. each character set occupies 76R bytes of memory. 

osudllv you will want to return to the system (CHR.SYS) 
Character set. The GraFORTH word CHRSET returns the address of 
this character set, 2048. Thus, to switch back to this display, 
you can type: 

Ready CHRStT CHRADR 

(Of course if you want to, you can overwrite this area of memory 
with another character set, too.) 
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The CHARED/TOR 



On the GraFORTH system diskette is a file called CHAREDITOR. 
This program enables you to read in character sets, examine and 
modify character shapes, create large block images that are 
stored as a series of characters, and save the new character sets 
to disk again. 

CHAREDITOR is one of ttie larger programs, so it would be a good 
idea to LIST the dictionary and FORGET any words you may have 
added before loading in CHAREDITOR. To load the program in, 
type: 



Ready READ " CHAREDITOR 



To run CHAREDITOR, type: 
Ready HOME RUN 

Notice that we cleared the screen before running the program, 
CHAREDITOR does not automatically clear the screen. This is so 
that any graphics images on the screen can be retained and used 
within the CHAREDITOR, allowing you to "pull" images and shapes 
from other programs into your GraFORTH character sets. 



Ik 



» :3 



You will see a list of commands to the right, the prompt 
"Enter command:" near the bottom of the screen, and a flashing 
dot in the upper-left corner. This flashing dot is the "drawing 
cursor" and will be used for creating your own character shapes. 



fir ' --^ 
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Selecting and Displaying the C/iaracter Set 

The character editor works with one character set at a time. To 
get an understanding of things, let's start by looking at the 
system character set that starts at location 2048. The editor 
uses single-letter commands. To specify the address of the 
desired character set, press "A" for Address. You will then see 
the prompt: 



mm. 
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Kntt?r Charset 

Work Area Address : 2Blfi 

The input cursor is fldshin<) over the "2H16". This is the 
diitault address, the address used if you do not specify one. You 
r.in keep this address simply by pressing <return>. However, we 
wdrit to enter the address of GraFORTH's standard character set. 
type "?0W over the top of the "2816" and press <return>. Now 
yn-J!! is the address of the character set used by the character 
e>! I tor. 

Type "0" for "Display characters". You'll see a display across 
the bottom of the screen of all the characters in the character 
set. in inverse. To the left are the numbers 0, 32, and 
Ihese are index numbers. When manipulating character shapes in 
CraFOKTH, character numbers in the range of to 95 are used 
instead of the ASCII values (which ranqe from 16(1 to 255 for 
prinlinq characters). The first row of characters are numbered n 
throuqh 31, the second row 32 through 63, and the third row 64 
throuqh 95. 

Displaying a Block of Characters 

If we want, we can take a sequential strinq of characters and 
display them in a rectanqular block on the screen. Let's display 
the 6 characters "n" throuqh "s" in a block that is 3 characters 
wide by ■> characters tall. To select a block of this si2e, press 
"B" tor "lilocksize". You will be prompted: 

tnter Block Horizontal Size : 

Fnter a 3 and press <return>. You will see: 

linTer Block Vertical Size : 

inter a ?, press <return>, and you will qet the reqular 

"Enter command:" prompt back. Also notice that 4 more dots have 

appeared at the top of the screen, outlining our 3 by 2 character 

block. 

Press "D" to bring the character set display back. Counting 
across the bottom row from the index number 64, you will find 
that the character "n" is character number 78. To display the 
block of 6 characters starting with "n", type "R" for "Read". 
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You wi 1 1 see: 

Enter character number 
to be read : 

We want character number 78, so type "78", The 6 characters will 
appear in the block surrounded by the 4 dots. 

You can also display blocks starting on other naracters, or use 
a different hlocksize. When changing blocksiz^ you may want to 
erase the block from the screen. To do this, imply type "E" for 
"Erase", then answer "Erase (Y/N) :" with a "Yl 

We've been looking at a block of standard charcters, to show you 
how block printing is done. Now let's see somt actual character 
graphics. To protect our precious system charcter set, press 
"A" and select an address of 2816 again, back nto open memory. 
Type "fi" for "Get". This option allows you toload a character 
set in from disk. You will see: 

Enter Load File Name : 

Type "CHR. STUFF ". This character set will loai into memory 
starting at the location 2816. Type "D" to diplay this 
character set. Except for a few punctuation sjnbols, those don't 
look much like characters! You can see piecesof the Insoft 
logo, parts of faces, and an assortment of line which are 
actually pieces of a helicopter used in the GrFORTH 
demonstration program. 

If you've changed the Blocksize, set it back t( 3 characters 
horizontally by 2 characters vertically. Now ype "R" and read 
character number 78. A smiling face will apper in the upper 
left. By pressing "D" again, you can see thatthis face occupies 
the same six characters that the characters "n' through "s" 
occupied in the system character set. The othr three faces 
begin at character numbers 84 and 90. Just prss "R" and enter 
the character number to see them. 

The Insoft logo uses a blocksize of 8 by 2 chaacters, and begins 
at character number 16. The three hel i coptersuse a blocksize of 
5 by 3 characters and begin at character numbes 33, 48, and 63. 
You will probably want to erase the block (witl"E") before 
changing the blocksize, so that part of the prwious image won't 
remain on the screen beside the new block. 
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Defining Your Own Shapes 



To create your own shapes with the chdracter editor, first select 
rt blocksize for the image you want to draw. Erase the block if 
ni'tessary. Here's where the drawinq cursor comes in. By 
urossHU! the I, J. K, and M keys, you can move this cursor one 
iiixel up left, right, or down within the block. If you want to 
)lot d point dt the position of the cursor, press "P" for "Plot'. 
To draw a line fron the last plotted point to the cursor, press 
"\" Notice that "P" and "L" are actually PLOT and LINE 
cuin'iands. with the coordinates specified by the cursor. The 
Character image is created by iiiovinq the cursor and drawing the 
points and lines that iiiake up the image. 

In addition, you can create character images in color. Press "C" 
for "Color" and enter the number of the color you want to work 
in fWhen colored character images are displayed in r.raFORTH, 
tne colors mav be different, depending on whether the image is 
drawn beginning on an odd-numbered coluinn or an even -numbered 
column. This comes about as a result of the way the Apple JL 
generates hi gh- resol u t i on color.) 

It you plot a point that you didn't want, you can erase it by 
l,.,'S4ing "U", which UNPLOTs the point. Similarly, you can erase 
lines by pressing "Z". If the drawing cursor moves too slowly, 
y,., ran increase its step size by pressing "X". then entering the 
number of pixels you want the cursor to move whenever you press a 
rursor-moving key (I. J, K, M). If your imaqe isn't coming out 
the way you'd 1 i ke. . . .wel 1 , press "E" to erase it and try again! 

Ixperiment with these keys to get a feel for creating images. 
All of the images in CHR. STUFF were created with the character 
editor. If you like, you can read an existing image from the 
tharacter set and use the drawing keys to modify it. 

When you've created an image that you want to save, first 
multiply the block vertical size by the horizontal size, to 
determine how many characters your image will occupy. Then press 
"0" to see the current character set, and choose a range of 
characters in the character set to write your image to. Press 
"W" for "Write". You will be prompted: 

Enter character number 
to be written : 
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Type the character number of the first character in the desired 
range. Your image will be written into the character set 
starting at that character. Press "D" again and vou will see 
your imaqe neatly dissected and placed in the character set. 

Images from one character set can be copied to another using the 
CHAREniTOR "T" ("Transfer") option. You will be prompted for a 
"From" address, a "To" address, and a length. To copy an entire 
character set from one address to another, simply enter the 
address of the character set to be transferred, the address of 
where it is to go, and enter 768 for the length. Remember that 
character sets are 768 bytes long. 

Transferring only part of a character set is a little trickier. 
Remember that each character occupies 8 bytes. Compute the 
"From" and "To" addresses based on the character number and the 
addresses of the character sets. The length is the number of 
characters times 8. 

Saving a Character Set 

After a new character set has been created, you can save it to 
disk to be used again later. To save a character set, press "S" 
for "Save" . You wi 1 1 see: 

Enter Save Fi 1 e Name ; 

Type the filename you've selected for the character set. Be sure 
that there are no files with that name on disk, unless you want 
to overwrite that file. Note that all of the character sets on 
the GraFORTII system disk begin with the prefix "CHR.". This is 
not a requirement; the prefix simply acts as a reminder that the 
file contains a character set. 

When you want to leave the character editor, type "Q" for "Quit". 
If you want to begin work with another program, it would probably 
be best to FORGET the character editor first, since it takes up a 
lot of room in the word library. The word "X" is the first word 
in the character editor, so to delete the editor, type: 

Ready FORGET X 
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Block Printing from GraFORTH 



Priptinq blocks of characters is done directly from GraFORTH much 
the same way as in the character editor. A character set is 
loaded into memory, an appropriate blocksize is se ected and a 
sequential ranqe of characters is printed in the block at the 
current horizontal and vertical position. 

Ifet's display sone of the same imaqes we saw earlier in the 
character editor. First, load "CHR. STUFF" back into memory: 

Redely CR 132 PUTC PRINT " HLOAO CHR. STUFF .A2816 " CR 

You could now type "2816 CHRADR" to select the character set. but 
remember that this character set doesn't have much in the way of 
r-Hcu-inizable characters! It contains helicopter parts and other 
thinns GraFORTH can recoqnize the characters fine, but the 
■scret-n display is unusable. When we display a character image, 
rte'll jump into the character set, display the imaqe, then jump 
back out. 

BLKSIZE 

The block size in firaFORTH is set with the word BLKSIZE. The 
mm for BLKSIZE is: 

<harizontal size> <vertical size> BLKSIZE 

As in the character editor, the horizontal and vertical size are 
measured in characters. BLKSIZE remains set until changed. The 
word ABORT does not reset BLKSIZE. 

To prepare to see the smilinq faces, set a blocksize of 3 
iharacters wide by ' characters tall: 

!<eacly 3 2 BLKSIZE 
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PUTBLK 



The word that actually puts the block of characters on the screen 
is PUTBU. PUTIiLK removes a number frrom the stack and uses it as 
the startinq character number for the block to he displayed, 
rhararter numbers ranqe from to 9S. as in the editor. The 
number of characters to he printed is determined by BLKSIZE. The 
position of the block on the screen iss set the same way text is 
positioned, with HTAB and VTAB, or thee other text positioning 
commands . 

Let's block-print one of the faces in CHR. STUFF. For this 
example, ty()e this entire line at oncee: 

Ready HOME 2Hlfi CHRADR 78 PUTBLK CHHRSET CHRAPR 12 VTAB 

"HOME" clears the screen and positionss printing to the upper-left 
corner, "2816 CHRAOR" sets the charactter set address for 
CHR SfUlF "/8 PiinUK" actually printss the image, "CHRSLT CHRAOR" 
resets the system character set, and ""12 VTAB" gets the following 
"Ready" prompt down out of the way, soo that it won't overwrite 
the block just printed. 

A smilinq face should have appeared irn the upper-left corner of 
the scret?n. 

To save on typing a bit, let's define? a couple of new words to 
help us in and out of the special chatracter set. We'll call 
these words "IN" and "OUT": 

Ready : IN 2816 CHRADR HOME ; 

Ready : OUT CHKSEI CHRAOR 12 VTAB ;; 

To display another face, we can simpljy type: 

Ready IN 84 PUTBLK OUT 

Unlike text printing, PUTBLK does not: update the horizontal 
cursor position. Therefore, once a pirintinq position has been 
established, several images can be drrawn sequentially in the same 
space. The following example prints Ithe three helicopter images 
in the same space 100 times. Keep yoDur eyes open; it's fast: 

Ready 5 3 BLKSIZE 

Ready IN 100 DO 33 PUTBLK 48 PUTBLK< 63 PUTBLK LOOP OUT 
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After thdnqirici the 'iloctsize, the Insoft 1090 (which starts at 
chdrdcter number 16) can he displayed centered on the screen: 

!^eady H 2 BLKSIZE 

Reddy IN 5 VTAB 15 HTAl-i 16 PUTBLK OUT 

We're beinq cautious about the display here because we're iiiixinii 
the printtiui of block imacies usiiui one character set with readin(| 
keyboard input usinq another. Most finished iirotirams will have 
thf^ changes planned out, so that the most effective mixing of 
character images and text display can occur. 

To erase a character image, the word UNBLK is used. IINBLK simply 
erases a block in the current blocksize at the current printing 
position. The following example erases the Insoft logo we placed 
on the screen: 

Heady b VTAB 16 HTAB UNBLK 

Ihe VTAR and HTAB determine the position of the block to be 
erased. Since IINBLK <foesn't print any characters, we don't need 
to specify a character set. 

Of course, character images can also be made larger by using 
CHRSlZt. This example displays the Insoft logo four times as 
1 a rge : 

Heady !N 3 CHRSIZE 1 COLOR 16 PUTBLK CHRSIZE OUT 

EXMODE Character Graphics 

Ciiaracter sizes 1 through 8 wilt be drawn in "EXMODE" if EXMODE 
is set. This allows you to draw characters or character images 
over other graphics, then erase them, leaving the original 
qraphics intact. However, EXMODE character graphics requires a 
few special considerations. 

As CiralORrn displays characters on the graphics screen, it stores 
the ASCII values for those characters in the text screen area. 
If a character about to be printed is already in place on the 
screen, no hi qh-resol uti on printing is done, since the character 
is already present. This saves much time in printing and 
scrol 1 inq. 
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I However, when usinq EXMODE, you usually want to reprint the same 

r- characters in the same location to cause them to disappear again. 

|w~.,att^~S Therefore, to unprint a line usinq EXMODE, you must first erase 
i the text screen (this is the actual Apple ][ text screen, not the 

i high resolution screen used by GraFDRTH) to force a reprinting. 

UN, 1 — , To'do this, you use the Apple ][ monitor's screen erase routine 

t ("-936 CALL"), then print the same line in the same position. 

i fhe following word definition Is an example of using EXMODE 

P character graphics. It draws a diagonal line, writes text over 

Us I ^ the line, then erases the text, leaving the line Intact. It 
r-^- ...^ repeats this 4 times; 
P 

1 : EXMODE. DEMO 

Ikkl ERASE 

^■^«~-J3 i CHRSIZE (Set up EXMODE character graphics) 

P EXMODE ^ 

I n PLOT ion 100 LINE (Draw the line to be written over) 

■»*- 1^ *^ 4 DO (Loop 4 times) 

*^ % 'H5 3000 DO LOOP (Delay loop, to slow It down) 

% b VTAB 

^- k 5 DO (Print the line 5 times) 

PRINT " This line can be erased " CR 

LOOP 

-936 CALL (Erase the text screen) 

LOOP 

CHRSIZE : 



■3 



k: 



3 



Summary 



^ :2! Output Characters 

GraFORTH uses two special output characters: ConTRoL-L erases 
^ the screen inside the text window, and ConTRoL-K causes a reverse 

^ line feed, making the screen reverse scroll If the cursor Is at 
the top of the text window. 



Character Sizes 

^ The GraFORTH word CHRSIZE uses a number from the stack to select 

a character size. Valid numbers are through 8. Sizes 1 



p — through ft can be'drawn in color using the word COLOR. Character 

size Is the normal text display. 
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Font Selection 



Vdrioui character fonts can be used hy BLOADinq them into free 
ineiiury and selecting that memory with CHRADR. GraFORTH's system 
ciiaracter set beqins at location 2048. The word CHRSET returns 
tnis address. 

CHARED/TOR 

The profiraiii CHARED 1 TOR is used to modify and save character 
shapes and images. Here is the normal sequence of events in the 
use of CHAREDITOR, with example entries: 

1. Load and run the CHAREDITOR proqram: 
Heady READ " CHARED 1 TOR " 

Read/ HOME RON 

2. Select a character set work address: 

Enter Charset 

Wurk Area Address : 2816 

3. (optional) Load a character set: 
Enter Load File Name : CHR. STUFF 

'1. Select a block size (single characters are always 1 by 1; 
i inaqes may be larger ) : 

Enter Block Horizontal Size : 3 
Enter Block Vertical Size : 2 

S. Draw the iniage or character using the described sketching 
Keys. 

r;. Write your image or character into the character set; 
Enter Character Number to be Written : 90 
7. Save the modified character set to disk: 
Enter Save File Name : CHR.TEST 
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B/ock Printing from Gra FORTH 



Displaying character graphics from GraFORTH usually involves the 
following steps: 

1. Load a character set into memory: 

Ready CR 132 PUTC PRINT " BLOAD CHR . STUFF ,A2816 " CR 

2. Select the character set: 
Ready 2816 CHRADR 

3. Choose an appropriate blocksize: 
Ready 3 2 BLKSIZE 

4. (optional) Select a character size and color: 
Ready 2 CHRSI7.E 1 COLOR 

5. Position the cursor and draw the block; 
Ready 5 VTAB 2 HTAB 90 PUTBLK 

Since PUTBLK does not advance the cursor, several blocks may be 
drawn on top of one another without having to reposition the 
cursor. The word UNBLK erases a block at the current position of 
the given blocksize. 

EXMODE Character Graphics 

Character sizes 1 through 8 may be drawn using EXMODE. This way, 
characters can be displayed over other graphics without erasing 
thein. However, to erase a line printed in EXMODE, the text 
screen must first be erased with "-936 CALL" before the line is 
repri nted. 
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Conclusion 



This chapter Introduced GraFORTrl's character graphics 
cdpabi H ties. So far we have covered the lanquaqe features of 
firjFORTH, its point and line graphics, and now the set of 
iiraphics that manipulate characters and block images. Next 
iJidpter, we'll introduce the most amazinq aspect of GraFORTH, its 
triri'e dimensional color graphics capability. So hold on to your 
keyboard, here we go! 
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Purpose and Overview 



PtTi.dDS the most exciting aspect of GrarORTII is its hiqh-speed 
3-ri iirdoMics capabilities. OrafORTH can manipulate up to 16 
, hrt-f--'li;'iensiofial shapes simultaneously. In this chapter we'll 
.iiicuSi how to use these features. 

' I I ^leuin with an overview of how 'i-diiiionsional shapes are 
dCLi">se:l anil manipulateO, anO qive you soi;ie i ntroriuctory 
e.,iiiiples. We'll then explain the various 3-D parameters and 
■ lisrijss the imaqe "format" in detail. We'll show you how to use 
rhe IMAiitfUTOK to create your own 3-0 images, then discuss 3-D 
■iispljy methods. Lastly, we'll iliscuss two very useful programs 
fur leveloping and man i pu 1 at i nq your 3-0 image files. 

3-D Graphics at a Glance 



To rlisplay a 3-0 object in GraFORTH, the "image" information 
Jescfihing the shape of the object is first loaded into a free 
jrea of iiiemorv, then commands are entered which tell the GraFORTH 
systen where the image is in memory, and how the image is to bo 
i' 1 bp ! J ye.!. 

i',r..'iMMH uses art internal Array to store the current information 
.1 in of the 3-1) objects being displayed. The array stores 

; ' I I oils m iiiciMor/ of the actual images and the display 
^j.-,.. •■tfi's ;i)osUiun, rotation, si-re, etc.). A number (frodi (1 to 

: ■> us-'d ti< refer to each object, and to select which object 
1-1 .:.uTeMtly rieiiiu manipulated. 

""o vu'w a 3-11 linage, let's first make sure things are bacl< to 

l A'ji .:ir. 1 : 

'<eu'!y AKOKT 

arui set a text window so that text doesn't scroll over our 3-0 
i ma qes : 

Red.ly 10 20 24 WINDOW ERASF 
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Now let's load an image from disk into a free area of memory. 
The binary file "XYZ" on the GraFORTH disl< contains an image of 
three arrows, each a different color, and each pointing a 
different direction. This is the same object that was used in 
the PLAY demonstration in Chapter 1. 

Ready CR 132 PUTC PRINT " BLOAD XYZ,A2816 " CR 

Before we can view "XYZ", we have to initialize the internal 3-0 
graphics array. Since we're starting from scratch, enter the 
word OBJERASE. OBJERASE clears the array, and should be used 
when beginning all 3-D programs. 

Ready OBJERASE 

Now we want to assign a number to the object we're about to view. 
Remember that GraFORTH can handle up to 16 objects at a time. 
The word OBJECT is used to specify which object to manipulate. 
OBJECT removes a number from the stacl<, and uses this number to 
select the current object. Let's give the image "XYZ" the number 
in the drn^i: 

Ready a OBJECT 

For our example, we will want the shape to be drawn automatically 
after each entered command. To do this, the word AUTODRAW is 
used. AUTODRAW removes a number from the stack. If this number 
is 1, then the currently selected object will automatically be 
drawn after each graphic command. If the number is 0, then 
automatic drawing will not occur. (Entering the word DRAW will 
draw the objects when AUTODRAW is not in effect.) Let's turn on 
automatic drawing with AUTODRAW: 

Ready 1 AUTODRAW 

We've initialized the array, set object number g, and turned on 
automatic drawing, but we haven't specified where the current 
object is in memory. The word OBJADR is used to specify this 
address. We loaded the object into memory starting at 2816, so 
this is the number we give to OBJADR: 

Ready 2816 OBJADR 

At this point (because AUTODRAW is turned on) the image will 
appear on the screen. Right now it looks like a single arrow 
with a line through it, but that's only because we're seeing it 
head-on. 
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(ir^itOKTH hds 1? separ.ite words for controlling the position, 
bwe, and orientation of 3-n objects. We'll introducii these 
wor;is properly in a hit, but to qive you a taste, let's rotate 
the iinaijy a little for better viewinq: 

Veady U VROT 

Now It's beiiinninq to come into view, and yoii can see parts of 
,1 M three arrows. Let's move it a litt:le more: 

Rt^aily 16 XROT 

and add a little pers|)ecti ve: 
Ready f. SCAL7 

3-D Image Format 

dust as two-dimensional graphics use Cartesian coordinates 
ijheU'd X and ¥, three-dimensional graphics use a Cartesian 
coorJiiidte system with the three directions labeled X, Y, and Z. 
■"he arrows in "XYZ" represent the three directions, or three 
'd«es'. X IS a point along the horizontal, from left to right, 
r li a point on the vertical, from top to bottom. Z is a point 
f roi'i rear to forward, pointing at the viewer. 

Hie points that make up a 3-0 image are expressed as three 
niiHt)r'rs, one for each of the X, Y, and Z coordinates. The valid 
fMiige for each of these numbers is -128 to +127. Each arrow lies 
on .iri dxis, with two coordinates equal to zero, and the ends of 
ei( ;i arrow re aching from -128 to 127. At the center of the cube, 
w'leie all three arrows meet, the three coordinates are all equal 
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The above diagram shows the limits for each of thie three 
coordinates. Note that these limits define a "cujbe of space", 
2^f> units along each side. All S-D objects residte in this space. 
When more than one object is being displayed, eacth object has its 
own 3-D space, though these spaces may overlap or even coincide 
on the screen. 

Image Parameters 



Once an image has been loaded into memory and sellected with 
OBJECT and OBJADR, it can be rotated, positioned,, scaled, and 
translated in a number of ways. 

Rotation 

An image can be rotated around any axis, using XWOT, YROT, or 
ZROT. XROT rotates the image around the X-axis, YROT around the 
Y-axis, and ZROT around the Z-axis. Each of thesie words removes 
a number from the stack and rotates the image to the selected 
angle. Angles are specified in units between t:o 256 rather 
than degrees. An entry of to YROT (or for that; matter, XROT or 
ZROT) rotates the image around to a normal positiion facing the 
viewer. An entry of 64 rotates to 90 degrees, 12'8 rotates to 180 
degrees, and so forth, until 256, which (like 3601 degrees) is the 
same as zero: a full revolution. 
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H Yi;nT nnrt YUOT to tip the imaqe a bit so that we 
, ,Mier. we used XRUT and ^' " ^ ^° ^ , , loop and cause the 

' \'l"rf:/,rc1rc e l following word definition 

to rotate a increasinq rotation value: E.— 

i.v'Ciit>'S YI<OT repeatedly, with an increa-,; i ! 

I 

:^6u 1)0 c - 

1 VHOT 

K I 

kc-ddy YSPIM * 

R,.,i,1y 14 YKOT ^ & 

,,0, and .ROT can. of course, be manipulated in identical ways. ^ " - 



Scaling 



.elect the qi ^en X or ^ , „folJed back" into »i» ■ 

, V, Nj.uhers outside of this range wi i ^ 1 

";<yZ" : I 

Heaqy 25 SCALX ^ | 

■,(,.<). 1y 8 SCALY *^ p 

I 

UeaJy 4 SCALX 1 

, ,„ie of zero causes the oh,1ect to have no "thickness" » 



at all: 



k.^d.y n SCALX 
r^eqative scale numbers reverse the imaqe 



Ready -8 SCALX 
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note- This reverse scalinq is useful in unexpected ways. For 
example if you are creatinq the imaqe of a bird, you only need 
one wing imaqe. The other winq is simply the first with one 
negative scale number to reverse the imaqe. 

Here's a proqramminq example of scalinq: 

Ready : SOUASH 12 -12 DO I SCALX LOOP ; 

Ready SQUASH 

Since for most qraphics applications you will want to chanqe both 
the X and Y scale to chanqe the total size of the object, the 
GraFORTH word SCALE is provided. SCALE has the same form as 
SCALX and SCALY. It simply sets both SCALX and SCALY to the same 
va 1 ue : 

Ready 5 SCALE 
Ready 12 SCALE 

Three-Dimensional Perspective 

There is a fourth scalinq word in GraFORTH, SCALZ. SCALZ doesn't 
change the size of the object in the same way that the other 
scaling words do; instead it changes the perspective of the 
object'. Entries for SCALZ are also in the range -31 to 31. The 
default value for SCALZ is zero, which doesn't provide 
perspective views. (The front of a cube, for example, will be 
the same size as the back.) If you enter a nonzero number for 
SCALZ, perspective will be provided. If the entry is positive, 
the front of the object will be larger than the back. If the 
entry is negative, "reverse perspective" occurs, a most unusual 
phenomenon! You may wish to try the following examples: 

Ready 20 SCALZ YSPIN 

Ready -10 SCALZ YSPIN 

Ready SCALZ YSPIN 

Note: When SCALZ is nonzero, images take about 20% longer to 
draw in exchange for the perspective features. 
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Also, SCALZ uses a fast alqorithin that closely approximates true 
perspective. However, if you are displaying an image that has 
ends of lines meeting at the middle of a line, and you are using 
large amounts of perspective, the image may begin to distort. If 
this hap()ens, break the image up into a series of shorter lines, 
so that all endpoints meet other enripoints, rather than meeting a 
line itself. 

Position 

Three-dimensional imaiies can also be placed anywhere on the 
screen with the words XI'OS and YPOS. XPOS and YPOS remove a 
number from the stack to determine the X or Y position on the 
screen of the center of the 3-0 cube. Especially if the scale is 
large, to avoid screen wrap-around, ample room must be left on 
either side for the edges of the images. The valid entries for 
XPOS are n to 255; valid entries to YPOS are to 191, The 
default values are 128 for XPOS and 96 for YPOS, which is the 
center of the screen. 

To move the image around, let's first make it a bit smaller, to 
avoid wrap-around, then try a few different positions on the 
screen : 

Ready 5 SCALE 

Ready 50 XPOS 

Ready 40 YPOS 

Ready 200 XPOS 

We can cause the feared wrap-around by placing the object close 
to one of the edges: 

Ready 5 YPOS 

Now let's move the image back to a more reasonable position: 
Ready 96 YPOS 



3-D GRAPHICS 



8-8 



Translation 



Translation occurs when tthe object is moved, not on the flat 
video screen, but within its own 3-dimensi onal space. In 
GraFORTH, obiects can be translated along the X, Y, or Z axis 
with the words XTRAN, YTRRAN, and ZTRAN. When usinq translation, 
you must keep the image i inside the confines of its "cube of 
space". If you do not, tthen "3-D wrap-around" will occur, 
because GrafORTH cannot rrepresent points outside of its cube of 
3-0 space. 

Our current image, "XYZ" already reaches to the edges of its 
space on all three axes. We can translate it, hut wrap-around 
will occur immediately; 

Ready 5 XTRAN 

For some examples of trannslation, let's first load another 3-D 
image, one that doesn't ffill its space. We'll load and set up 
the image "HOUSE": 

Ready ERASE 

Ready OR 13? PUTC PRINT "" BLOAD HOUSE, A300n " CR 
Ready 1 OBJECT 3000 OBJAADR 

The image of a house shojuld appear. Let's get a better view: 
Ready 20 XROT 
Ready 10 YROT 
Ready 8 SCALZ 
Ready 10 SCALE 

Now the house can be trannslated. It can be moved about a bit 
before causing wrap-arounnd. (In the next section, you'll see how 
to determine the true sizze of an object from the IMAGEDITOR.) 

Ready -50 ZTRAN 
Ready 50 ZTRAN 
Ready -25 XTRAN 
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)„st for Un. try usinq YSPIN wUh the house, now that it has 
ileen tr.n.l Jed away fro,,, the center of Us space: 

Reddy YSPIM 

Object Color 

[urrent obiect. The usual GraFORTH color numbers are used. 

The house does not have a set color, so we can set its color with 

Oil J COLOR: 

RediiY 1 OBJCOlOR 
Keaily OlSJCOLOR 



Note that 3-D graphics. liKe two-dimensional and character 

'.h c can be done in either INVERSE or NORMAL and either 
■1, MOOL or EXMODE. producing a wide variety of ^^^P*^^ "^'^^ ^^f„ • 
W,: encourage you to try some 3-D graphics commands with vanous 
L,o,"binations of display modes. 

At the end of this chapter is a discussion of the program PLAY. 

,i-h^nables you to set all of these para,neters (except for 
OB c5lO n oTot on. PLAY is very useful in getting an 
,ntuUiv; feel for exactly what each of these parameters does. 

Th e image Editor 

on the GraFORTH syste.n disk is a file called I^J^EDITOR which 

^r^sl-h^ -aJe-.UoJl-l^rd^lte-S ^ ^^'^ 
library to make room, then type: 

Reaify ABORT 

Ready READ " [MAGEDITOR " 
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(NOTE: The image editor is a fairly l.large program. On 
non-language card systems, loading thee image editor will move the 
top of the word library into the same i memory used by the text 
editor program. If the editor is loadded into memory, it will 
overwrite the top of the word library,, forcing you to reach for 
the power switch, as the GraFORTH systtem will become inoperable. 
After using the image editor, rememberr to FO RGET the pr ogram 
before usin g th e text edito r. ) 

Now run the program: 

Ready RON 

You will see a list of commands to thee right and a prompt: "Enter 
co,imidnd:". The image editor works witth one 3-0 image at a time. 

Address and Image Selectionn 

As in the character editor, you must sselect a work area address 
(or use the default address). To seleect an address, press "A" 
for "Address". You will see the prompipt: 

Enter Fi le Address : 

followed by the number "2816". (You sshould he getting pretty 
familiar with that number!) If you wa/ant to use another area of 
memory, enter that address. For this; example, just hit <return>, 
and the address 2816 will be selected,!. 

If you are doing these examples sequennti al ly . the image "XYZ" 
will still be in mei,iory at 2816. If yyou ' ve turned the Apple off 
Since that time, you will need to loadd it again. Type "G" for 
"Get" and enter the filename "XYZ". TThe file will be loaded into 
memory . 

Getting a Good View 

If the image was already in memory, itit won't appear until you 
rotate it or move it on the screen. I Images can be rotated, 
positioned, and scaled from the imagei editor. 

To rotate the image, type "R". You wi(ill see: 

Rotate [ X (nuni) to Z (num) ] : 
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I^or this coiiinidnd enter the letter of the axis you want to rotate 
around followed by the anqle you want to rotate. For this 
^..ihiple. type ' Y16 . The imaiie will rotate around the Y-axis. 
]ypn "r" aqciin and enter Xlh . How you can see the arrows well. 

]o sole the object, type "S". You will see the prompt: 

Scale [ (nuin), or X.V,/ (num) ] : 

To scale X and Y siniul taneously , sinply enter a number. To scale 
one of the coordinates, type X, Y, or Z, and then the scale 
number. Since we're keepinq the image in the corner of the 
screen, it's best to keep the scale small. The scale is 
Kii-.idl ly set to fi. 

To change the position of the object, type "P". You will see: 
Position [ X (num) or Y (num) ] : 

Knter an X or a Y followed by the desired screen position. The 
iiiiaqe has an initial screen position of X=64 and Y=43. : X Tt> 

You can choose a color for the iniaqe, if the color is not already 
set in the image file. Press "C" for "Color" and enter the 
■desired color number. You can also choose between EXMODE and 
ORMODE views. Press "M" for "Mode", then enter "X" for EXMOOE or 
"0" tor "OKMOPE". 



Image File Entries 

Now type "1." for "List" to see the numbers that make up the 
i,i.dge. You can press <return> to see all of the entries or press 
roriTUoL-C to stop. Remember that, as explained above, GraFORTH 
uses Cartesian coordinates, a system of three numbers for each 
defined point. 
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Each entry in the IflAGEDITOR listing has the following 
information : 

1. Whether the point is to be (M) moved to without drawing, or 
(0) drawn to from the previous line endinq, (This means that 
each image file must begin with (M), not (n), since there are 
no previous lines at that time.) 

? What color should be used for the line. The color number (if 
present) is directly under the letter "C" In the heading. 
(If it is desired to use the word "OBJCOinR" to specify 
object color, then don't make any color entries within the 
i ma ge file.) 

3. The X, Y, and Z coordinates of the point (each coordinate 
lies within the range to 12Z). 

4. The address of the entry. Each entry occupies four bytes. 

The last six lines of the image file can also he seen by pressing 
"E" for "Enter". We will use the "Enter" command in a moment to 
create our own 3-D shape. For now. press <return> to leave the 
"Enter" mode. 

While using the image editor, you may want more screen space for 
text and less for image drawing, or vice versa. To accomplish 
this you can use "W" to move the text window up or down, position 
the image using "P". and scale the image using "S". The "List' 
and "Enter" commands will use as many lines as the text window 
al lows. 

Sometimes, while adjusting the image position, the image will 
"wrap around" on the graphics screen. If you want to clean up 
the screen, type "W" and reenter 14 or some other window top 
value, "w" clears the screen when it sets a new window. 

Creating New Images 

Now we will create our own image, a cube. First, we need to 
erase "XYZ". Press "Z". and you will see: 

Erase File (Y/N) : 

Type a "Y" to erase the file. The image won't disappear right 
away. (If the presence of the old image disturbs you, press "W' 
and enter 14 to cause the "Window" command to erase the screen.) 



3-D GRAPHICS 



8 - 13 



',u thdt we will he able to sec all sides of our object as it is 
crertted, enter a 1 scdle of 8 for perspective (press "S", then 
"ZH"). flow press "E" again. Notice that no file entries are 
listed, since we have erased them. You will see a prompt: 

(M)ove, (n)raw, (-) Delete, (CR) Quit : 

Since the first entry must be a move, type "M". You will be 
|)rnirintei) for a color. Let's not use a color, so that later we 
vdH select Its color with DBJCOLOR. .lust press <return>. 

You will then be prompted tor X, Y, and Z values in turn. We're 
Moinn to start with the point at the lower left front corner of 
1 lie cube. X at the left is -Vll , so enter -127 and press 
(return>. Y at the bottom is 127. Enter 127 and press <return>. 
I at the front is 127, so enter that and press <return>. 

Y.)i; Still won't see anythinq drawn, because we have only defineil 
a single point, and points aren't plotted in GraFOKTH 3-1) 
iiraphics, only lines. Now let's draw our first line. Type "D" 
this time instead of "M". Now enter an X value Df 127 (remember 
the last entry was -127). We want the other two values to stay 
the same. In this "Enter" mode, to keep a previous value, just 
press <return>. The last value will be repeated. Press <return> 
tor Doth Y and Z. Now a line will appear from left to right 
! frmn X - -127 to X - 127). 

fiuw repeat the entry procedure, pressing "0" each time and 
changing only one number per entry, pressing <return> for the 

others: 

I to -127 
x to -127 

dmi Z to 127 again. 

These entries will draw a square at the bottom of the image 
space. (If the view isn't very good, press <return> to leave 
"uiter" mode, chanqe the rotation or the scaling, then press "E" 
10 return to "Enter" mode.) 

Note: If at any time you make an incorrect entry, just finish 
the entry, then press "-". "-" deletes the last entry in the 
file. 

Now if we change Y to -127 and repeat the entire procedure, we 
will iidve most of the cube. 
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At this point three edges are still missing. Can you figure out 
how to draw the missing edges? 



The solution is to (M)ove to each of the following locations, and 

(O)rdw a vertical line (using Y) from bottom to top: 

1. (M) X = 127, Y = 127, Z = 127 

2. (0) X (same), Y = -127, Z (same) 

3. (M) X (same), Y = 127, Z = -127 

4. (n) X (same), Y = -127, Z (same) 

5. (M) X = -127, Y = 127, Z (same) 

6. (D) X (same), Y = -127, Z (same) 



Saving the Image File 

Now we can save our cube. Press <return> with no entry to leav° 
the "Enter" mode, then press "K" for "Keep", You will be 
prompted : 

Enter File Name to Keep : 

Enter a file name here. The GraFORTH system diskette already 
contains a file named "CUBE". (It contains a cube identical to 
the one we just made here.) If you're using another disk, you 
can use the filename "CUBE" or another filename. 



Three Dimensional Display Methods 



From within a program, the word DRAW is usually used instead of 
AUTODRAW to draw 3-D images. This way, several parameters can be 
changed at once before the next image is drawn. When AUTODRAW is 
off, executing DRAW causes the images to be drawn. 

Aside from the mathematical methods (described in Appendix B), 
GraFORTH has a rather complex display method for 3-D images. In 
general, when a DRAW command is issued, the following events 
occur: 
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1. The drawing routines are directed at the graphics screen that 
is not currently beinq displayed, so that the drawing won't 
t)e seen. 

The previous image on the invisible screen is "undrawn", 
using information stored when it was drawn. 

3. The new imaqe is drdwn. 

4. The display is switched to the freshly drawn screen. 

This method quardntees hiqh-quality animation images, since the 
untire process of drawiiiq is concealed from the viewer. 

you may wish to note that character graphics, discussed in the 
last chapter, also draws to _borJi^ screens, so that character and 
3-0 graphics can be freely intermixed. 

Redrawing Without Change 

For iiidxiiiiuffl speed, an object is only redrawn by DRAW if a new 
coiiiaiand is issued to it. So in a program with several objects, 
only those that have been referenced since the last DRAW will he 
redrawn. Example: 

(I OBJECT 16 XROT 

J OBJECT ?4 YROT 
DRAW 

Only objects and 3 will be redrawn when DRAW is executed. 

If an object has been changed and then drawn, the images of the 
object on the two graphics screens will not be the sane. If 
other objects are then repeatedly changed and drawn, causing 
OraFORTH'to switch graphics screens, then the two unlike images 
of the object will be alternated, causing a back-and-f orth type 
of residual motion. 

Thererore, if several objects are being drawn independently, they 
siiould be re fere nced (using the word OBJECT), if not changed, to 
cause the image to be redrawn. This way, the images on both 
graphics screens will always be updated. For example, 

1 OliJECT 

causes a redraw of object 1 at the next draw command. 
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Erasing Individual Objects 



The r,raFORTH word OFF is used to "undraw" an object hut not 
redraw it. Host objects stay on the screen after the last image 
entry to their tables. OFF selectively erases objects that are 
no longer needed. Subsequent commands to an object will redraw 
it. Here is an example of OFF: 

Read:y 3 OBJECT OFF 

Overlapping Objects and UNDRAW 

In ai case where there are several overlapping objects, or objects 
are drawn over text, it is best to use "EXMODE". since this 
causes drawing and undrawing to occur without destroying the 
screen's original contents. Alternatively, if all the objects 
are in continuous motion, it may be desirable to use the word 
UNDKAW. 

UNDRAW simply erases a block of character spaces specified hy 
BLKSIZE, iust as UNBLK does. However, UNDRAW also causes the 
next draw' command to not do an automatic line "undraw" before 
dra'^ing the next image?" This way, you can use UNDRAW to erase 
the 3-D images yourself. Using UNDRAW is frequently faster than 
the automatic line undraw that is carried out by DRAW. 

For example, let us say we have an image in the center of the 
screen (at X = 128, Y = 96) that extends 20 plotting points in 
radiius around this point. Remember that numbers entered to 
BLKSIZE refer to characters, not points. Text characters of size 
are 7 points wide and 8 points high. So an entry to BLKSIZE ot 
6 hv ') will cover an area 42 by 40 points, large enough for our 
sample image. Remember that UNDRAW, like UNBLK, is controlled by 
VTA5 and HTAB. Let's set the blocksize, then position and 
execute an UNDRAW before the next DRAW: 

Ready 6 5 BLKSIZE 

Ready IH VTAB 17 HTAB UNDRAW DRAW 
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Remember also that UNORAW, like PUTHLK and UNRLK, doesn't advance 
MTAR across tlie screen as for printing. Once positioned, ilNnRAlJ 
can be used repeatedly over the same area. 



Other Effects 

!f you wish to prevent' undrawi nq of the imaqes (for special 
effects), simply use UNIIRAW, hut place the undraw block away from 
the iniaiie. For speed, select a blocksize of 1 by 1 in this case. 

ll is also possible to prevent screen sequencing altogether, 
using SEQUENCE, so that the process of drawing may be observed. 
SEQUENCE removes a number from the stack. If this number is a 0, 
screen se()uencinq is tiirned off. If the number is 1, screen 
sequencing is turned back on. This example will stop screen 
sequencing; 

Ready fl SEQIIENCF 

usually used with "0 SEQUENCE", the word "SCREEN" selects which 
graphics screen to display. The screens are numbered and I. 
This example displays screen nunber 1: 

Heady 1 SCREEN 

PROFILE 



Utere is another program on the GraFORTH system disk used for 
Lreatinq 3-D images, called PROFILE. PROFILE acts as a sort of 
■ irapMics "lathe", creating images that are cylindrical in nature 
from d set of points defining the profile of the image. The file 
"CfiAi." on disk contains the image of a chalice, and is an example 
ut the kinds of imaqes that can be created with PROFILE. 

lo run PROFILE, first make sure that there is room on the word 
library by FORfiETting any extra words, then type: 

Ready READ " PROFILE " 

Ready RUN 
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Setting Parameters 



You will see the PROFILE heading and sofiie instructions. We're 
going to use PROFILE in this example to create a simple cone. 
The first question asked is: 

Enter number of polygon sides : 

This determines how smooth the cones circumference will be. For 
a perfect circle, you would ideally want to enter an infinite 
number of sides. Unfortunately, your Apple does not contain an 
infinite amount of memory! For this example, enter a 

The next prompt reads: 

Enter Object File Address : 

with a good ol ' 2H16 already selected for you. Images created 
with PROFILE can easily use a lot of memory. Usually you will 
want to use the area of memory beginning at PHI'S or the space 
above the word library. (To find this address, print the 
value of PKfiTOP after loading PROFILE, and add about 50 or 100 to 
this address for extra space.) For this example, just press 
<return> to keep the address 2G16. 

Entering Data from the Keyboard 

Now you w1 1 1 see : 

Data from [Kjeyboard or [D]1sk ? 

You can either enter the profile coordinates directly from the 
keyboard or use a text file that contains the coordinates. Here 
we will enter the coordinates directly. Press "K" for 
"Keyboard". You will see: 

Enter X.Y pair (end - "E") : 

This is where you actually enter the coordinates. The Y 
coordinate Is the vertical position In the profile. The valid 
range 1s -128 to 127. The X coordinate can actually be 
considered a radi us , since It determines the distance from the 
edge to the center of the object. Its valid range 1s also -128 
to 127, but negative entries are identical to positive ones, so 
only numbers from to 127 need be used. 
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Entering Data from Disk 



discussed earlier, PROFILE can also read a list of coordinates 
rroni a disk file. The textfile "BlfiCHAL" contains a list of 
coordinates that describes the profile of a chalice. You may 
wish to see this list at some point. When PROFILE is no lonqer 
in iiieiiiory, you can enter the text editor, get the file BIGCHAL, 
and list It. You will see a list of numbers similar to the one 
we entered to make the cone, but longer. Note that the last 



We're going to start our cone as a single point, and work down. 
The top of" the cone is at Y = -128. and the radius (X) is zero. 
As we move down with increasing Y values, we'll also steadily 
increase the radius. Make the following entries: 

Enter X,Y pair (end = "E") : 0,-l?8 
Enter X.Y pair (end = "E") : 32,-64 

Enter X,Y pair (end = "E") : 64,0 c 

Inter X,Y pair (end = "E") : 96,64 
Enter X.Y pair (end = "E") : 127,12/ 

Enter X,Y pair (end = "E") : E MIp, 
The last entry must be "E". For a few seconds, the phrase: 
Generating image file (rt24 bytes) . . . 

will appear on the screen as PROFILE computes the points that 

nuke up the cone, then the screen will be erased and the cone 

will appear. Notice that the cone has 20 vertical lines around 

i;;s circumference. This is because we selected 20 polygonal 

iiiles. There are 4 circles around the cone and a point at the 

top. 'These are because we made S profile entries. At the bottom 

ol the screen will be the message: Jj^ — 

Enter ob.iect fi le name : 

This is so you can save the 3-0 object to disk. If you want to 

save the cone to disk, enter a filename and press <return>. If 

yuu don't want to save the image, just press <return> and the 

p r^jgraiii will end. _ 
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entry in the file is "E", marking the end of the list. 
For now though, let's run PROFILE again, this time using the 
textfile BIGCHAL instead of keyboard entries. RUN the program, 
select 8 polygon sides, the address 2816, then "D" to read data 
from disk. You will then be prompted: 

Enter Data Fi le Name : 

Enter the name "BIGCHAL". The disk will whir for a bit, then the 
message : 

Generating image file (2724 bytes) ... 

will appear. After a pause, the chalice will appear on the 
screen. As before, you can either save the 3-0 image to disk, or 
press <return> to exit. 

Memory Considerations 

Because PROFILE can generate very large image files rapidly, 
image size checking has been added to help prevent overwriting 
important parts of memory. 

Usually you will use one of two areas of memory for the 3-0 image 
file when using PROFILE: either the free space from locations 
2816 to 5887, or the space above the top of the word library. If 
you select an address between 2816 and 5887, PROFILE will prevent 
the image from extending beyond location 5887. 

If you select an address greater then 5887, then PROFILE assumes 
the image is above the word library. It then checks for the 
presence of a language card. If you are using a language card, 
PROFILE will allow images to extend to location -16385, 
immediately below the Apple ][ I/O area. If you do not have a 
language card, PROFILE prevents the image from extending beyond 
location -26113, immediately below DOS. 

If the image is too large to fit in the provided space, the image 
will not be created or drawn, and the following message will 
appear : 

Not enough room here. 
(Requires nnnn bytes.) 

with nnnn being the actual number of bytes the image requires. 
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Notice that if the starting address you select is in a "safe" 
area of memory, then PRilFILF will prevent the iinaqe from 
clobherinq important information. However, if you select an 
address in the middle of soinethinq important, you'll find 
yourself having to reboot the system from scratch..,. 



PLAYing Around 



The proqram PLAY was briefly introduced in Chapter 1. PLAY was «^-.« "3 

designed for you to "play" with a 3-0 image, manipulating its "^T ""fl 

rotation, scale, translation, and position parameters. Any or | 

all of these parameters can he set into motion, giving you a r— 1 

fdpiil intuitive "feel" for what each of the parameters does. And ^ 

I'LAY IS a lot of fun! S 

Noie that PLAY, like I MAOFI) I TOI! , uses the same memory as does Ihf — I 

text editor on non-language card systems. Be sure to forget any fcn*"" ^2 

extra words in the word library (PLAY is rather a large program), ^ 

then type: | 

Ready KLAD " PLAY " 

Ready RUN _ I 

The instructions are fairly self-explanatory. Once the image is j't^ 

loaded and you begin "playing", you can select a parameter with | 

one of the nunber keys. To set the parameter in motion, press | 

one of the arrow keys. The right arrow increases the parameter !»„ . , ~-n 

value; the left arrow decreases it. By pressing several number *^ 1 ' ^ 

keys and arrow keys alternately, you can set a number of | 

parameters in motion at once. _ | 

If any one parameter gets out of hand, you can press "F" to j !!S 

"freeze" its motion, leaving it at the current value. You can | 

also press "D", to bring it back to Its "Default" value. , - j 



If you want to pause everything, iust press ConTRoL-S. The 

display will pause, and a flashing cursor will appear in the I 

upper-left corner. Just press any key to resume. If you ^ i 

want to bring everything to a complete halt, press ESC. All ^.u, ' 1 
motion will stop and all parameters will be set back to their 

default values. Finally, typing "?" will display the instruction \ 

screen again, and "Q" will quit the program. ' 
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Let's answer the start-up questions and get things moving: 
The first prompt you will see is: 
Image in [M]emory or on [0]isk? 

If you already have an image in memory, press "M". If you want 
to load an image from disk now, press "D". For this example, 
press "D". Next is the now-famous address question: 

Enter image address : 

again with the number 2R16 waiting for you. If you want to use 
the address 2816, just press <return>; otherwise enter the 
address you want. Press <return> for this example. If you 
selected to load an imaqe from disk a moment aqo, you will then 
see: 

Enter image f 1 lename : 

Type the name of the file you want to load. Let's load the file 
"HOUSE". Lastly: 

Press Return to begin... 

The screen will be erased and the imaqe will appear. Along the 
right side are the values for each of the parameters. When you 
press a number key, the selected parameter will also be displayed 
on the bottom line with its current value and increment. 
Pressing the arrow keys will change the increment and set the 
object in motion. 

You'll also see a question mark in the lower right corner. This 
is just to remind you that the instructions can be displayed at 
any time by typing "?", 

With PLAY, it's very easy to get some of the parameters out of 
bounds, causing screen or "space" wrap-around. It doesn't hurt 
anything, and it can sometimes produce rather amusing effects! 



3-D GRAPHICS 



8-23 



Conclusion 



We've now looked at all three kinds of qrdphics: two-dimensional 
iiraplilcs, character qraphics, and three-dimensional qraphics. 
With the information presented in those chanters, you can 
incorporate a wide variety of animated color graphics effects 
into your own programs, then use SAVEPRG to produce a system that 
hoots and runs them automatically! 

The next chapter explains how you can create music and sound 
etfects with GraFORTH. (We'll also mention another program you 
may he interested in...) So without any further delay, on to 
chapter 9! 
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CHAPTER NINE: MUSIC WITH GRAFORTH 



Chapter Table of Contents: Page 

Introduction 9-2 

VOICE 9-2 

NOTE 9-3 

Determining Duration and Pitch 9-3 

Useful Music Words 9-4 
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Introduction 



GrdrDHfH (idS a sophi st i Cdted inusic synthesizer that plays through 
the A(iple ][ built-in speaker. Notes may be played in nine 
.iiitHict voices (not simultaneously). These features allow you 
to iiu-orporate music or sound effects into your applications or 
Mdiiit? prcqraDis. 

The two GraFOIUH words that control the synthesizer are VOICE and 
NOTE. 

VOICE 



The GraFURTH word VOICE selects one of 9 voices in which to play 
notes. VOICE removes a number from the stack, and uses it to 
select a (jiven voice. Here are the VOICE numbers and their 
mt-cin i ni|s : 

Number Voice ^ , . 



-6 to -! Selects a constant 'duty cycle' for the note, 

producinq a note that is constant in volume. -1 = W 
duty cycle, -?. = 2b% duty cycle, -3 = 12.5% duty 
cycle, etc. Smaller duty cycles decrease volume and 
increase the amount of hi qh-f requency energy in the 
note. 

Note begins at bOX duty cycle, then decreases to 0%. 
The note seems to die away. 

1 The note begins at 0%, increases to 50%, then 
decreases again. 

2 The note begins at 0%, then increases to 50'*,. The 
note seems to increase in volume. 
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NOTE 



The nraFORTH word NOTE actually causes a note to be played. NOTE 
removes two numbers from the stack toi select pitch and duration, 
then plays the note. The form for NO)TE is: 

<pitch> <duration> NOTE 

The valid numbers for pitch and duration are in the range 2 to 
255. Larger numbers for duration pro)duce longer notes. Larger 
numbers for pitch produce lower pitchied notes. 

Let's play a couple of notes. The voice used if one has not been 
selected is voice 0. This example plays an "A" two octaves below 
middle A: 

Ready 1^4 255 NOTE 

Let's try a different note: 

Ready 62 128 NOTE 

This plays a note an octave higher fo)r half as long. Now let's 
change the voice and play the same note: 

Ready -1 VOICE 

Ready 62 128 NOTE 

Notice the change in tone quality. Experiment with the different 
voices to hear their differences. 

Determining Duration and Pitch 

The duration of a note is directly related to the size of the 
duration number. 255 can be considered a whole note, 128 a half 
note, 64 a quarter note, and so forthi. Of course, if you want to 
play notes at a faster tempo, simply use smaller numbers. 
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Ht^re is a table relatinq notes to the pitch numbsrs which produce 
theiii : 



M a 1 1^ 


Octave ] 


Octave ? 


Octave 


3 Octave 4 


A 


?-1H 


124 


6? 


31 


A * 


?3-l 


117 


SB 


29 


H 


?2\ 


no 


55 


?7 


c 


?0'1 


104 


52 


26 


en 


147 


qa 


.19 


24 


1) 


I HI, 


93 


46 


23 


on 


1 


87 


43 


21 


E 


166 


83 


41 


20 


1^ 


ISb 


78 


39 


19 


f f» 


147 


73 


36 


18 




139 


60 


34 


17 




131 


6S 


3? 


16 



Useful Music Words 



It you don't want to look up the pitches for each note, you can 
use the followinq proqram to generate the table and store it in a 
strinq array called "PITCH". Each element of PITCH, instead of 
cunijinimi a character, contains the pitch value for a note. 

50 STRING PITCH 

: COMPUTE. NOTES 
24870 

48 00 

OOP 100 / I PITCH POKE 

DUP 18 / - 

OOP 1655 / - 
LOOP DROP ; 

Ready COMPUTE . NOTES 

Kunninci COMPUTE .NOTES qenerates the table in PITCH. Now the 
pitch values for the 48 notes (numbered throuqh 47) can be 
found by reading the value from the proper element of PITCH. For 
example, the pitch value for the note 3 in the table (a "C" from 
the first octave) can be found in position number 3 in PITCH: 
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Ready 3 PITCH PEEK . 
209 

To play this note as a half note, you can enter: 
Ready 3 PITCH PEEK 128 NOTE 

You can also define a short word that retrieves the pitch value 
for you: 

Ready : GETPITCH PITCH PEEK . ; 

Ready 3 GETPITCH 
209 

This word can be used with NOTE: 
Ready 3 GETPITCH 128 NOTE 

Since the notes are now numbered from to 47, we can play all of 
the notes in the scale by using a loop: 

Ready 48 DO I GETPITCH 32 NOTE LOOP 

With a little patience, we can put together a song! The 
following word definition plays the first phrase from the "Happy 
Birthday" song: 

: HAPPY. B 

12 GETPITCH 50 NOTE 

12 GETPITCH 50 NOTE 

14 GETPITCH 100 NOTE 

12 GETPITCH 100 NOTE 

17 GETPITCH 100 NOTE 

Ifi GETPITCH 200 NOTE ; 

For longer tunes, repeating the words GETPITCH and NOTE will 
waste a lot of space. We wanted to show here how simply the 
tunes can be constructed. A much more efficient method is to 
store the numbers in memory or on the stack, and read them and 
play the notes from a loop. 
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Postscripts 



Note- The quality of the synthesizer is higher than can be 
demonstrated with the Apple ][ built-in speaker. The use of a 
large external speaker is recommended for serious music work. 
See the Apple ][ Reference Manual or your local dealer for 
connection information. 

for two-part music applications, the Electric Duet, also written 
by Pdul Lutus, is available from Insoft. The Electric Duet plays 
2 simultaneous notes through either the Apple speaker or an 
external amplifier, and can be used to play music directly from 
your GraFORTH programs. It contains a full feature music editor 
with the ability to transpose both note pitch and duration. 
Music can be directed to either the internal speaker or the Apple 
jr tape output jack. The suggested price of the Electric Duet is 
(inly $29.95. For more information, contact Insoft or your local 
Apple dealer. 
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CHAPTER TEN: FINAL WRAP 



We've made it! You have now been introduced to the GraFORTH 
system from language featurres to complex graphics. From here on 
out you will probably be ussing this manual more as a reference 
guide than as a tutorial; thierefore, we suggest you get 
acguainted with the appendices. You will find the Word Library 
listings invaluable, and thee Index very helpful for finding those 
definitions you've forgottem. The technical data section covers 
very useful information we ssuggest you at least browse through, 
and the GraFORTH diskette fiile listing and ASCII code tables are 
excellent references when ycou need them. 

Please note that if you are using or intend to use GraFORTH to 
develop software for re-sale, we would like to talk with you. 
Insoft represents fine software (such as this!) for Apple, IBM, 
Atari, NEC and other popularr microcomputers. Our royalty rates 
are among the best in the irndustry, and our support team is 
second to none. Let us shovw you why using our team of 
professionals makes good sernse! 

If you decide to market sofitware on your own, please call us for 
information on a license agreement to use GraFORTH. There is no 
fee for this license, howevier, we do have a few restrictions on 
TT^M it is marketed (We'll ;show you how to lock GraFORTH so that 
only your program can be rum.) Either way, please contact: 

Michael Brovwn 
Insoft 

10175 SW Bairbur Blvd. Suite 202B 
Portland, Oiregon. 97219 
(503) 244-41181 

You now have a graphics sysitem that is quite nearly limited only 
by your imagination! We hojpe you enjoy learning and using 
GraFORTH as much as we have; enjoyed the opportunity to bring it 
to you ! 
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APPENDIX A: 

WORD LIBRARY LISTING 



— - 

^ The following is a list of the words in the GraFORTH word 

^Z, library. The list includes the word name, a "before and a ter 

^ itack oicture the page number in the text where the word is 

nrst introduced, and'a brief description of what the word does. 

The stack picture shown represents relevant "^"^J^/^^, °" J 

thP ^tack as letters. The top of the stack is to the ri qht . as 

ndicated by dash. Three dashes represent an empty stack. How 
^ords ufe Se stack can usually be inferred simply from the stack 
IJS picture. 

The word descriptions here are not ,.«ant to be comprehensi ve. 
, ^ For more information on each word, we suggest you refer back to 

T"::^ the text, using the page numbers provided. 



Word Name 



GraFORTH WORD LIBRARY LISTING 
Before After____ Page 



3- 13 

'a set of quotes surrou'nd'ing text causes the text to be compiled 
into the program. Used with PRINT. ASSIGN, and READ. 

$UST - 

Lists words in word library with hexadecimal addresses. 

a - 5-30 
a = address of the word that follows '. and prevents that word s 
execution. 

4- 14 

Indicates the beginning "of a program comment, to be passed over 
by the GraFORTH compiler. 
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GraFORTH Word Library Listing 



Word Name Before After 



* m n - p - 3- in 

p = III » n (muUi pi i cat i on ) 

t m n - P - 3-6 

p ^ m + n (add i t i on ) 

+ LOOP n - 3-?0 



Marks the end of a loop structure, usinq n as a loop value 
1 ncreitient . 

5-32 

Compiles a simile byte within word definitions. 

_ m n - p - 3-10 
p = III - n (subtraction) 

-> (not applicable) 5-8 

Causes the next variable reference to store the top stack value 

into the variable, rather than placinq the variable value on the 
stack. 

- 3-6 

Prints n. 

/ ni n - p - 3-1^ 

p = ni / n (division) 

- 3-14 

Mafks the beqinning of an executable word definition. 

3-14 

Marks the end of a word definition. 



< n ni - p - 3-?3 

p - 1 if n < m, otherwise p = n. 

n m - p - 3-23 

p - ! if n <= m, otherwise p = 0. 
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GiraFORTH Word Library Listing 

Word Name Before After Page 



<> n m - p - 3-23 

p = 1 if n <> in, otherwise p = 0, 



= n m - p - 

p = 1 if n = mi, otherwise p = 0. 



3-23 



^ > n m - p - 3-23 

p = 1 if n > rni, otherwise p = 0. 



>= n m - p - 

»«■» p = 1 if n >= ni, otherwise p = 0. 



3-23 



ABORT 7-3 

Restarts GraFlORTH from scratch. The screen is erased, character 
size of 0, color of 3, all stack pointers initialized to n. 



ABS n - m - 3-10 

m = absolute (numeric value of n. 

""""^ AND n m - p - 3-23 

p = 1 if both n and m are nonzero, otherwise p = 0. 

^ AREG (variable) 5-31 

Value of AREfi; is placed in processor A register before a CALL. 
After CALL, aontents of A register are loaded back into AREG. 



ASSIGN a - 5-12 

Places following quoted text into memory starting at address a. 



r- ^ AUTODRAW n - 8-3 

»^ ^ If n is nonze^ro, 3-D objects will automatically be drawn after 

every graphic: command. If n is zero, this feature is turned off. 

k AUTORUN n - 5-26 

I*. Zf! If n is nonze;ro, the top word library word will automatically 

execute at ev/ery return to the system. If n is zero, this 

feature is tuirned off. 
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Gra FORTH Word Library Listing 



WorJ Nditie Before After Paqe 

BASE (variable) 5-22 

Vdluf (letennines what base numbers are accepted and displayed in, 

BEGIN 3.29 

Provides a proqrdiii return point for the words REPEAT and UNTIL, 

BELL 3-3 

Beeps the Apple speaker. 

BINARY 5.22 

jl-Ls number input and output to base two. 

BLKSIZE h V - 7-12 

Selects a blocksize of h characters horizontally by v vertically 
fur use by PUTBLK, IINBLK, and UNDRAW. 

BYE 5-32 

txits GraFOHTH to Apple monitor. 

CALL a - 5-31 

Li.dds processor registers from AREG, XREG, YREG, AND PREG, calls 
ifidchine lanquaqe routine at address a, then stores register 
va ' ues . 

CASE: n - 3-32 

Selects and executes nth following word from list of words 
riunibered starting from 0, 

CHRADR a - 7-6 

Selects a as address of current character set. 

CHRSET (variable) 7-6 

Vdiue IS address of default character set (204R). 

CHRSIZE n - 7-3 

Selects character size for subsequent character printing using 
PHINT, WRITELN, PUTC, and PUTBLK, 
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^z:::::^ GraFORTH Word Library Listing 

^ Word Nane Before After Page 

" 

CHS m - n - 3-10 

^ n = - m (change sign) 

^ CLEOL 5-4 

Clears from the cursor position to the end of the current line. 

CLEOP 5-4 

~" Clears from the cursor position to the end of the text window. 

i;;^^ CLOSE 5-24 

Causes DOS to close any open files. 

CLRKEY 5-20 

iifc" Clears the Apple ][ keyboard strobe so that a key can be read 

:2 with GETKEY. 

^ COLOR n - 6-6 

•iu Selects the color for line and large character drawing. 



CR 3-13 

Prints a carriage return (ASCII value 141). 

— DECIMAL 5-22 

Sets number input and output to base ten. 

DO m n - 3-19 

" Initializes a loop, using n for an initial value and m as an 

ending value. 

DRAW 8-15 

Causes all 3-D objects referenced since the last DRAW to be 
drawn, using 3-D display methods. 

3 DROP n - 3-7 

Discards n from the stack. 

— " DUP n - n n - 3-7 



It, ■-•^ 



Makes a copy of n on the stack. 
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Gra FORTH Word Library Listing 

Word Name Before After Page 



EDIT - 4-? 

lo.iili rnim disk (if necessary) and runs the appropriate text 
ed 1 1 or. 

ELSE 3-27 

Sepdfdtt'S the two controlled areas in an IF - ELSE - THEN 
con i t rue t . 

EMPTY X y - 6-8 

Fr.tbes a rectangular area from the last plotted point to (x,y). 

ERASE 5-4 

l.rises f.uth graphics screens. 

EXMODE 6-10 

Cdijst-s plotted points to turn on corresponding screen locations 
that, are off, and turn off locations that are on. 

FILL X y - fi-4 

Ill's a rectangular area from the last plotted point to (x.y). 

FORGET - 3-17 

^ruiicdies the UraFORTH library back to the word that follows 

lOK'aEl'. 

GETC n - 5-20 

i-.r'M a single character from the keyboard, placing its ASCII 
value on the stack. 

GET KEY n - 5-20 

•iedi's the keyboard without waiting, returning an ASCII value. 
Vdlut-s over 128 are valid. Should be followed by CLRKEY. 

GETNUM a - n - 5-14 

c:u'iverts text string at address a into a number. Unsuccessful 
i..a(i vers i ons return 0. 
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Word Name Before After Page 



GPEEK X y - n - 6-12 

Examines point at screen coordinates (x,y). n is nonzero if 
point is turned on, or if point is turned off. 

GR - 3-38 

Reestablishes normal GraFORTH input and output, and sets the 
grapiiic display mode. 

HEX 5-22 

Sets number input and output to base 16. 

HOME - 5-4 

Erases the screen inside the text window and sets HTAB and VTAB 
to tiie upper left corner of the window. 

HTAB h - - - - 5-3 

Sets the column for subsequent printing. 

! n - 3-19 

Retu-ns the current innermost loop value. 

IF n - 3-25 

If n is nonzero, words between IF and THEN (or IF and ELSE) are 
execited, otherwise execution continues after THEN (or between 
ELSE and THEN). 

INVERSE 6-9 

Complements the color for all text and graphics displays 
(including black-on-white text). 

J n - 3-20 

Returns the loop value for the next outer loop. 

K n - 3-21 

Returns the loop value for the third outer loop. 

LINE X y - 6-4 

Draws a line from the last plotted point to (x,y). 
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Gra FORTH Word Library Listing 



Uor-'l Name Before After Page 



LIST 3-3 

Lists the words in the GraFORTH word library. 

LOOP - 3-19 

Mdrks the end of a loop structure, i ncreinenti nq the loop value 
,in.i loopinq hack to the word after nO if the loop value is less 
ttidii the ending value. 

MAX m n - p - 3-10 

p - the greater of iii or n. 

MEMRD a - 4-13 

r(eci(Js and compiles text in memory starting at address a. 

MIN n, n - p - 3-10 
p i the siiia 1 1 er of m or n . 

MOD m n - P - 3-10 
[- - remainder after dividing m by n. 

MOVMEM a h n - -^-30 

Moves a block of n bytes from address a to address b. 

NORMAL 6-9 

Kesfts normal color (white-on-black text) display. 

NOTE p d - 9-3 

houMds a note of pitch p and duration d in the current voice. 

OB J ADR a - B-3 

iielects a as address of currently selected 3-D object. 

OBJCOLOR n - 8-10 

Selects color of current 3-n object. 

OBJECT n - 8-3 

Selects which object subsequent 3-D commands will refer to. 
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Word Name flefore After Page 

OBJERASE fi-3 

Initializes the 3-D image a>rray. Should be used at the beginning 
of 3-n graphics programs. 

OFF fi-17 

Causes tlie next DRAW commaind to undraw the 3-D object. 

OR m n - p - 3-23 

p is bit-wise OR of m and ni. (p is nonzero if either m or n is 

nonzero, otherwise p = 0. ) 

ORMODE 6-10 

Causes points to be plottedl regardless of what screen locations 
are on or off. 

OVER m n - m n m - 3-7 

Copies m to top of stack. 

PAD a - 5-lB 

Returns the address (812) 0)f a 12n-byte string space. 

PEEK a - n - 5-6 

Reads a single byte n from address a. 

PEEKW a - n - 5-6 

Reads number n from address, a. 

PICK ..mn- ..mp- 3-7 

Copies the nth stack item too top of stack. 

PLOT X y - 6-4 

Plots a point at (x,y). 

POKE n a - 5-6 

Stores single byte n at addlress a. 

POKEW n a - 5-5 

Stores number n at address .a. 
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Gra FORTH Word Library Listing 

Wor<1 Name Before After Paqe 



READ 4-14 

K'eads and compiles text from file with following quoted filename. 
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POP 3-?? CT- _ 

Discards top return stack value. | 

POSN X y - 6-6 m- i _ -jj 

Lstablisties a position for a "'last plotted point" without p*—— ^ 
plottirii). i 

PREG (variable) 5-31 Z ^ 

Value uf PKEG is Stored in processor status register before a ' — 1 
CAi I . After CALL, value of status register is stored bacl< into i 

PRGTOP a - 3-3 — „ 

Returns the address of the top of the word library. ^ 

PRINT 3-13 E-"'-^ 

Prints followinq quoted text. B 

PULL n - 3-2? ^ 1 ^ 

Moves top return stack value to data stack. IIL — •a^ 

PUSH n - 3-22 I 

Moves top data stack value toi return stack. ET 

PUTDLK n - 7-13 | 

Draws a block of characters with present blocksize starting with g 

c'l.iracter number n at the current cursor position, EiT ^ 

PUTC n - 5-19 i 

iTints character with ASCII value n at the current cursor 
pos 1 t i on . 



READLN a - 5-12 » 

Reads a line from keyboard into string starting at address a. g 



GraFORTH Word Library Listing 



Word Name 



Before After 



REPEAT - - - - - - 2-31 

Marks the end the BF.GIN - WHILE - REPEAT construct, causing 
execution to jump liack to words following BEGIN. 



RND 

n is a random number. 

RNDB " - , 

n is a random number from to 2bb. 

RUN ' 

Executes the top word on the word library. 

SAVEPRG 

Saves current system to disk. 

SCALE n - - - - 

Sets the X and Y scales for the current 3-D object. 

SCALX n - " " " 

Sets the X scile (width) for the current 3-0 object. 

qCALY n - - - - 

SetVthe Y scale (height) for the current 3-D object. 

QrAI7 n - ^'^ 

Sets the Z scile (perspective) for the current 3-D object. 
Faster drawing occurs with a SCALZ of 0. 

SCREEN n - ^-^^ 



3-10 

3-10 
5-26 
5-27 
8-7 
fi-6 
8-6 



Selects display of the given graphics screen (0 or 1). 

8- ] 8 

ff^^^^l^'^lomatic sc'reen sequencing for 3-D drawing is enabled. 
If n - 0, sei^iencinq is enabled. (Default-1) 

3-in 

SGN m - n - ^ 

n = I if m > n, if m = 0, -1 if m < 0. 
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GraFORTH Word Library Listing 



Won I Name Before A fter Page 

SIN n - n - 3-10 

ti is d scaled sine value for m, in the range -128 to 127, 
reiiejtinq for every 12R numbers. 

SPCE 3-13 

Prints A space (ASCII value 16(1). 

STACK 3-5 

T(i(iqles ttie stack display on or off. 

STRING '^-9 

Declares a string array with followtng name, setting aside number 
of characters specified before STRING, 

SWAP in n - n m - 3-7 
Swaps position of top two stack values. 

TEXT 3-38 

Reestablishes normal GraFORTH input and output, and sets text 
.iisplay I'lode (no graphics). 

THEN 3-25 

Marks the end of an IF - THLN consfrMCt, where execution 
continues from. 

UNBLK 7-14 

leases a block with present blocksize at the current cursor 
p;i', itiun. 

UNDRAW 8-17 

1 rases a block and prevents the next DRAW from performing an 
dutoiiidtic line undraw. 

ONLINE X y - 6-8 

Erases a line from the last plotted point to (x,y). 

UNPLOT X y - 6-8 

Erases a point at (x,y). 

UNTIL n - 3-29 

It n - n, execution jump back to words that follow BEGIN. 
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GraFORTH Word Library Listing 



Word Name 



Before After Page 



VALID - - - n - - 5-14 

n is nonzero if last GETNllM produced a valid number, otherwise n 

= 0. 

VARIABLE ^'^ . • 

Declares a variable with following name. Any preceding number is 
used as the variable's initial value. 

VOICE n - l'^ 

Sets the voice for subsequent NOTE commands. Valid numbers are 

-fi to ?-. 

VTAB n - 5-3 

Sets the row for subsequent printing. 

WHILE n - 3-31 

If n is nonzero, execution continues after WHILE, otherwise 
execution jumps to words after REPEAT. 

WINDOW L w t b - 5-3 

Sets a text window with left margin L, width w, top margin t, and 
bottom margin b. 

WRITELN a - ^"12 

Writes text to screen from string at address a. 

XPOS n - 

Sets X-position of current 3-D object to n. 

XREG (variable) 5-31 

Value of XREG is placed into processor X register before a CALL. 
After CALL, value of X register is stored back into XKtb. 

XROT n - . V ■ . ^"^ 

Sets rotation of current 3-D object around X-axis to n. 

XTRAN n - 

Translates current 3-D object along X-axis by n. 
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GraFORTH Word Library Listing 



Word jldi^ne Before After Page 

yPOS n - 3-8 

Sets r-posUion of current 1-1) object to n. 

YREG (vdridhle) 5-31 

Value of yREG is placed into processor Y reqister before a CALL 
Atter CALL, value of Y reqister is stored back into YREG. 

VHOT n - 8-5 

Sets rotation of current 3-D object around Y-axis by n. 

YTRAN n - 8-9 

Translates current 3-0 object alonq Y-axis by n. 

ZROT n - 8-5 

Sets rotation of current 3-0 object around Z-axIs by n. 

ZTRAN n - 8-9 

Irani Idtes current 3-0 object along Z-axis by by n. 
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APPENDIX A: WORD LIBRARY 
BY SUBJECT GROUP 



Numeric Operator Words 



CHS 
MIN 



AiiS 
MAX 
> 

OR ANO 
DROP POP 
PULL PUSH 
MOO / 
SIN RASE 
MOVMEM VALIO 



SON RNI) 

POKEW POKE 

< > = 

PEEKW PEEK 

I J 

OOP OVER 



DEC I MAE 
OETNUM 



BINARY 



RNOB 

<> 

<= 

SWAP 

K 

PICK 
HEX 



Program Branching or Control Words 



+ LOOP 


LOOl' 


00 


REPEAT 


WtllLE 


LINTIL 


BEGIN 


lE 


THEN 


ELSE 


BYE 


STACK 


FORGET 


VARIABLE 


RUN 


AOTORDN 


ABORT 


REAO 


MEMRD 


EDIT 


CASE: 


( 


CLOSE 


PROTOP 


SAVE PRC 


-> 







Input/Output Operator Words 



HOME CLEOP CLEOL GETC GETKEY 
CLRKEY PUTC . $LIST LIST 



Text Display Function Words 

VTAB HTAB CHRAOR CHRSET CR 

cpcE rtXT WINDOW PRINT ASSIGN 

STRING PAD READLN WRITELN 
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Genera/ Graphics Words 



UX GPEEK OkMOnE EXMODE ERASE 

fOLOR INVERSE NORMAL 

Two-Dimensional Graphics Words 

POSM PLOT IINPLOT LINE UNLINE 

MLL EMPTY 

Character Graphics Words 

PDTBLK CHRSI7E BLKSIZE UNBLK 

Three-Dimensional Graphics Words 



SCREEN DRAW SEQUENCE UNDRAW AUTODRAW 

OBJECT OBJADR OBJERASE OBJCOLOR SCALE 

SCAlX SCALY SCALZ XPOS YPOS 

XTRAN YTRAN ZTRAN XROT YROT 

ZROr OFF 



IVIisceilaneous Words 



CALI PREG AREfi XREG YREG 

NOTE VOICE BELL 
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i APPENDIX B: TECHNICAL DATA 

^ Table of Contents ^^^^ 

n ^ GraFORTH Memory Map 

I B-3 

II Page Zero Map 5.4 



>■ II m 



p 



Mathematical Method 
Image Table Format 



TECHNICAL DATA 



B-5 
B-6 



I Word Library Structure and Compilation b-7 



B-1 



GraFORTH Memory Map 



n to 


$0000 to 


$OOFF 


2';h to Sll 


$0100 


to 


$01FF 


61? to 767 


$0200 


to 


$02FF 


?68 to an 


$0300 


to 


$0326 


ai? to 935 


■ $032C 


to 


$03A7 


93r, 10 975 


$03A8 


to 


$03CF 


97b to 1023 


$0300 


to 


$03FF 


to 2U47 


$0400 


to 


$07FF 


21148 to 2815 


$0800 


to 


$09FF 


7816 to 5887 


$0B00 


to 


$16FF 


5888 to 6655 


$1700 


to 


J 1 9r r 


6fi5fi to 7679 


$1A00 to 


$1DFF 


;68n to ;935 


$1E00 to 


$1EFF 


79Jn to 8191 


$1F00 to 


$1FFF 


8192 to 16383 


$2000 to 


$3FFF 


10384 to 24575 


$4000 


to 


$5FFF 


?45?6 to -32256 


$6000 to 


$8200 



6502 Page Zero. See Paqe Zero 
listing below. 

6502 Stack 

GraFORTH Line Input Buffer 
3-0 Matrix scratch-pad area 
Compiler Stack, PAD String Area 
Graphics Horizontal Color Buffer 
DOS Link Area 

Text Display Screen (used for 
graphics also) 

Primary character set storage area 

>>> User Free Space <<< 

Image position and rotation data 
(See the Image Data listing below.) 

Graphics address lookup tables 

Data stack 

Return stack 

Graphics screen 

Graphics screen 1 

GraFORTH System as delivered 
(Address approximate) 
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GraFORTH Memory Map 
Without Language Card 



-30720 


to 


-28673 


$8800 to $8FFF 


Text editor file area (when used) 


-2R972 


to 


-26113 


$9000 to $99FF 


Text editor program (when used) 


-26114 


to 


-16385 


$9A00 to $BFFF 


DOS 3.3 


-163R4 


to 


-12289 


$C000 to $CFFF 


Apple ][ hardware I/O 


-12288 


to 


-1 


$D000 to $FFFF 


Apple ][ ROM area (Basic. Monitor) 



With Language Card 

-30720 to -18945 $8800 to $B5FF Text editor file area (when used) 

-18944 to -16385 $B600 to $BFFF Text editor ppogram (when used) 

-16384 to -12289 $C000 to $CFFF Apple ][ hardware I/O 

-12288 to -1 $DOO0 to $FFFF DOS 3.3 and Monitor 



GraFORTH Page Zero Map 

000-031 ($On-lF) not used 
032-n79 ($20-4F) Apple ][ monitor use 
neo $^0) GraFORTH text pointer 1 2 bytes 

082 $52 GraFORTH text pointer 2 2 bytes 

U54 GraFORTH graphics pointer 1 2 bytes 
Si6 ($56) GraFORTH graphics pointer 2 (2 bytes) 
096-127 ($60-7F) not used (some DOS uses) 
128-256 ($8n-FF) used by GraFORTH 
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Useful locations in Page Zero: 



\?A CSan) last plotted X position 

'.ill (SB?) last plotted Y position 

I'jft {?!5t^) pointer to data stack 

!57 ($90) pointer to return stack 

?18-?SB ($L1A-FF) paqe zero matrix work area 

Image Data Map ^ 

There are three data sets: _ 

588H $17(10 undraw 
614'1 1,1800 interim 
6400 $1900 draw 

fach data set contains 16 data tables, one for each of the 16 
possible objects. Each data table is 16 bytes long: 

u 

Function Relative Byte 

Flaq (draw, nodraw) 

XROl 1 

VROT 2 "i- 

ZROT 3 

XTRAN 4 

YTRAN 5 C" 

/!TRAN 6 *»- 

XPOS 7 

YPilS 8 ^ 

.'jtALX 9 CT. 

SCALY 10 
11 

OBJCOlOR 12 ^ 

liiiaqe Address 13 and 14 ^' 



Each table begins at a multiple of 16. Therefore to find the object 



color for object 3: ^ 



16 ' 3 (object 3) + 12 (object color offset 
t 6400 (data table base address) = 6460 
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Three-Dimensional IVIathematical 
l\/lettiod 



The three-dimensional display meethod used in GraFORTH ][ uses a system 
of matrices that are successi velly multiplied to provide the ultimate 
position for each line in the diisplayed image. 

In the following diagrams, (X) tthrough (Z) refer to rotation angles, 
and X through Z refer to cartesiian scalar values. 



Matrix 1: 

Scale X 

n Scale Y 

n Scale IL 
Matrix 2: 

1 

COS(X) -SIN(X)) 

SIN(X) COS(X)) 
Matrix 3: 

COS(Y) -SIN(Y)) 

1 

SIN(Y) COS(Y)) 
Matrix 4: 

COS(Z) -SIN(Z) 

SIN(Z) COS(Z) 

1 
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This iDdtrix trdnsformation occurs once per imaqe. Then the result 
matrix IS iiseil to transform each line position using this last matrix; 



X.xTKAfJ y + YTRAN Z + ZIRAN 

U 

(i 

After tliis, if a nonzero value has been selected for SCALZ, a 
persijcctive computation is made (in which case image drawing is about 
2(n H!ow<'r). The plotting coordinates then are offset by the 
liser-proviilt'il XPOS and YPOS values, and the line is drawn. 

Image Table Format 



lnt"-c are four liytes for each line entry in the 3D data table. Three 
uf tri,.'se 6,/tes are one-byte signed numbers having a range of -12fi to 
1''/, and nfie byte contains data about color and whether to position or 
f i r a w a 1 1 n tf ; 

! L-,u h ent ry , 

s^- ! bit 7 (nigh bit) Is set if a line is to be drawn, clear 
t'n-rwi'.c. tilts fl-2 contain a color number 0-7 (if zero, no color 
injn :fi. bsp (it zero is recommended, this makes it possible to control 
>olor trom tne program using OBJCOLOR. 

'ivtes ,-'-■3 are X, V , and Z positions within the 30 space. 

The end of the image table is indicated by having the data byte (1) be 

e^:idl to 2SS ($FF). 
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Word Library Structure 

and Compilation 

Each word entry in the library consists of three parfts: 

1. A "pointer location" containing the address of thf.e next lower word 
in the word library. 

2. The word name (ASCII characters with high bit sett). 

3. The executable machine language code for the wordd. 

The hexadecimal numbers displayed by $LIST are the aaddresses of the 
potnte? locations. A number returned by tic (') is the address of the 
executable portion of a word. 

During compilation. GraFORTH separates the input linne by sP^cesJ-ito 
indivLal words, then searches through the ibrary for ea h word 
For each word search. GraFORTH first reads the curreent va ue of PRCTOP 
to find the top of the word library. It then looks here to find a 
orinter containing the address of the top word withiin the word 
uZ\n Beg nning with this first word, it followss the pointers from 
io do" word down through the library. At each wordd. a check IS made 
to see irthis is the word being searched for. If tthe word is not 
found he search falls through to a routine which eattempts to convert 
[rw;>rd Into a number. If this routine fails, the. "Not Found" error 
is given. 

P.ogra. lines are compiled directly 6502 machi.ne language^ in^the 

" 1 aiS^orp^rt of a word defiinition the machine 
anoua^e code is executed, then promptly forgotten.. If the line s 
iart of a word definition, the code is saved, not eexecuted. and the 
word library expands. 

At execution time, calls to other words are made thhrough direct 
^cMoe language jumps. This 1s a major factor in the speed of 
GraFORTH. 
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Appendix C: Disk File Directory 



1 I Pit 


Pi! P M A M 
r 1 1- L fi 81" L 


LENGTH 


REMOVE OKK? 


B 


nn 1 ^ no TN 
Un J • r UK In 


36 


NO 


a 
D 


(\w 1 rn I TOR 1 

UnJ . L u I I ur\ i 


11 


YES, IF fi64K 


a 
P 


no 1 pn I TOR? 


11 


YES, IF mt 




rij AO C D T THD 
LnAKt iJ 1 1 UK 


21 


NO 




I u ft r r n I tod 
1 MALjLiU I UK 




NO 




rKijf 1 1. 1 


15 


NO 




UIK ! L t 




NO 




PLAY 




NO 




STRING WORDS 


>1 
H 


NO 


B 


CHH .SYS 


C 


NO 


B 


CHK. STOP 


[; 



I L J 


B 


CHR. SLANT 


c 


YES 


8 


CHK . BY 1 1 


c 


YES 


B 


run p riT u 1 


5 


YES 


B 


LHK . o 1 Ur r 


5 


YES 


a 



rMi> Mfl ^ UF 1 I 


5 


YES 


ni 1 CD V 


2 


YES - DEfMO 




HI ftlJt K 




YES - DEfMO 




MtNu 




YES - DEfMO 




uKHr M I 1. J 1 


a 


YES - DFPMO 




bK Ar M 1 L Oi: 


(3 


YES - DEfMO 






10 


YES - DEfMO 




Try T fir Mil 


12 


YES - DEfMO 




r UK 1 nUL jL 


17 


YES - DEfMO 




r LLlltKnnUO 


12 


YES - DEfMO 




PIANO 


11 


YES - DEfMO 




CLOCK 


5 


YES 


B 

B 


TETRA 


2 


YES - 3D) 


XVZ 


2 


YES - 3D) 


8 


BAT 


2 


YES - 3D) 


B 


CUBE 


2 


YES - 3D) 


B 


HOUSE 


2 


YES - 3D) 


B 


CHAL 


10 


YES - 30) 


T 


BIGCHAL 


3 


YES - PROFILE 



C - 1 



1,^ 



Appendix D: 

ASCII CharactersJiEq^^ 



I* -IT, lin»..J^ 



i 
I 



i 



DEC 

i^a 

1?4 
130 
131 

132 
133 
134 

]y> 

13h 
13/ 
13li 
134 
110 
HI 
142 

143 

144 

14^) 

14h 

14/ 

148 

Ibn 

151 

l')2 

153 

!54 

155 

15h 

157 

158 

159 

160 

Ifi! 

\u? 

163 

164 

U'S 

If.t, 

in; 

168 

169 



Set High Bit £.1.631 

HEX M 



fill 
81 
>\2 
.33 

84 

KH 

H(i 

iV 

8R 

(14 

HA 

HB 

fiC 

81) 

BE 

HF 

90 

91 

9? 

93 

94 

96 

9o 

97 

98 

99 

9A 

9;! 

9C 

41) 

9L 

9F 

Ai) 

Al 

A? 

A3 

A4 

AO 

Ao 

A? 

A8 

A9 




1 

?. 
3 
4 
5 
6 
7 
8 
9 

in 
11 

12 

13 

14 

lb 

16 

17 

IH 

19 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

¥i 

1/ 

38 

39 

4(1 

41 



00 

01 

02 

03 

04 

05 

Ofi 

07 

08 

09 

OA 

013 

nc 

00 
OE 
OF 

in 

11 

12 

13 

14 

15 

16 

17 

18 

19 

lA 

IB 

IC 

ID 

IE 

IF 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 



(Bell) 

(Left Arrow) 



(Return) 



CHAR 

r,onTnol--('' 
ConTRoL-A 
ConTRoL-Q 
ConTRoL-C 
ConTRoL-O 
ConTRoL-E 
ConTRoL-F 
ConTRoL-G 
ConTRoL-H 
ConTRoL-I 
ConTRol.-J 
ConTRoL-K 
ConTRoL-L 
ConTRoL-M 
ConTRoL-H 
ConTRoL-0 
ConTRoL-P 
ConTRoL-O 
ConTRoL-R 
ConTRoL-S 
ConTRoL-T 

ConTRoL-U (Right Arrow) 

ConTRoL-V 
ConTRoL-W 
ConTRoL-X 
ConTRoL-Y 
ConTRnL-2 
Escape 

Reverse Slash 
1 

lip Arrow 

SPACE 
! 

# 
$ 
% 
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APPENDIX D: ASCII CHARACTERS AND EQUIVALENT NUMBERS 



Set 


High 


Bit c 






DEC 


HEX 


DEC 


HEX 


CF 












1 7(1 


AA 


i? 


2A 


* 


Wl 


AH 


43 


?H 


t 


1 '' 


AC 


44 


2C 






Ai) 




20 


- 


1 


AC 


46 


2E 




1 ;'s 


At' 


47 


2F 


/ 


1 /h 


'SO 


48 


30 





1 11 


HI 


4q 


31 


1 


I 1 H 


li? 


51) 


32 


2 




H3 


51 


33 


3 


IHII 


Ii4 


52 


34 


4 


1 Ml 


HS 


53 


'15 


5 


1.'.:' 


lib 


54 


36 


6 




R7 


55 


37 


7 


1 '\i 


KH 


56 


38 


8 




HO 


57 


39 


9 


1 


HA 


58 


3A 






liH 


59 


3H 


; 




BC 


6D 


3C 


< 




HI) 


61 


3D 


= 


1 9(1 


HE 


62 


3E 


> 


i 1 


HP 


63 


3F 


? 


IQ;,. 


0) 


64 


40 


(3 




CI 


65 


41 


A 


1 'J 4 


C? 


66 


42 


B 




C3 


67 


43 


C 


! 41. 


C4 


68 


44 


D 


; -i ' 


CS 


69 


45 


E 


1 4.1 


C6 


70 


46 


F 


; 44 


C7 


71 


47 


G 


/Oil 


ca 


72 


48 


H 


ynl 


C4 


73 


49 


I 


?()>' 


CA 


74 


4A 


J 


-'I) J 


CH 


75 


4B 


K 


?(I4 


CC 


76 


4C 


L 


?(i5 


CI) 


77 


4n 


M 


?0f> 


CE 


78 


4E 


N 


2iJ7 


CF 


79 


4F 







on 


80 


50 


P 


?04 


lU 


81 


51 







112 


82 


52 


R 


?l 1 


D3 


83 


53 


S 
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APPENDIX D: ASCII CHARACTERS AND EQUIVALENT NUMBERS 



Set 


High 


iit 


Clear 




DEC 


HEX 


DEC 


HEX 


PU A D 

LHAK 


212 


D4 


84 


54 


1 


213 


D5 


85 


55 


D 


214 


D6 


86 


56 


V 


215 


D7 


87 


57 


W 


216 


D8 


88 


58 


X 


217 


D9 


89 


59 


Y 


218 


DA 


90 


5A 


Z 


219 


DB 


91 


5B 


r 

L 


220 


DC 


92 


5C 


Reverse Slash 


221 


DD 


9 J 


5D 


J 


222 


D£ 


94 


5E 


Hp Arrow 


223 


OF 


95 


5F 




224 


EO 


96 


60 




226 


El 


97 


61 


a 


226 


E2 


98 


62 


b 


227 


£3 


9') 


63 


c 


228 


E4 


100 


64 


(] 


229 


E5 


101 


55 


e 


23n 


E6 


102 


66 


f 


231 


E7 


103 


67 


q 


232 


E3 


104 


68 


h 


233 


E9 


105 


59 


i 


234 


EA 


106 


6A 


,i 


235 


EB 


107 


5B 


K 


236 


EC 


108 


6C 


1 

t 


237 


ED 


109 


6D 


in 


238 


FF 


! 10 


6F 


n 


239 


EF 


111 


6F 





?4l) 


FD 


1 1? 


70 


P 


241 


Fl 


113 


71 


q 


242 


F? 


1 14 


72 


r 


?43 


F3 


1 15 


73 


s 


244 


F4 


116 


74 


t 




v s 


1 t 7 
1 1 / 


75 


u 


?46 


F6 


118 


75 


V 


?47 


n 


119 


77 


w 


248 


F8 


1 20 


78 


X 




F 9 


I'l 


79 


y 


?sa 


FA 


12? 


7A 
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3 XlCH3<l<iV 



Ox-5 sbuuis buLUi^ao 

gg-£ spjOM uoLspaa 

Z2-5 -1VW1030 

a 

EI-C «3 

sabeuJi O'E Buiiea-'D 

l^-l pasn suol;u3'>uo3 

El-fr 6uL[Ldiuo3 

dg-E sjaquuHN buuediiioo 

6i-g 3MVdW03 

^l-^ J01LP3 'sjuauwo: 

9-9 a0303 

OZ-g A3Xdi: 

W-S 3S013 

V-g dU313 

t,-g 30313 

OI-E SH3 

e-z 3zisaH3 

g-L i3SyH3 

z-z aoiia3avH3 

f,|-g butsii 'SJ3l3PJeM3 

t-U inSV 'sjaiOPJBMD 

g-^ s^as Jai3ejPL|3 

(--^ azLS Jajopjei^o 
soiMdpjg J^^^eJel^3 

EE-E =3SV3 
t,-9 sajBu^pjooo up^sa^jeQ 

lE-y TlVD 

D 

ZE-S 3Aa 

ij-l buuuMd ^30ia 

y-/ abeiui )|30ta 

zi-z 3Zis>na 



77-c AHVHI9 

-E ^139 
N1938 

„-c sash's 
22 -g 3SV9 
g-X saido3 dn)(3?9 

gg.g wnaoiw 

^-(^ J051P3 'lu'iuo-jny 

£-8 MVHOOinV 

ZI-S NDlSStf 

g-£ spJOM DHaiug^uv 

lE-5 "^'^^^ 
E2-E 

(,-5 sasssjppv 

UI-E S9V 

e-z iaoav 

EZ-E 

EZ-E ^ 
EZ-E 

EZ-E <> 
EZ-E ■=> 
EZ-E > 
EZ-E 

t-I-E ■ 
Ol-E ' 

9-E 

«-S 

01- E ; 

ZE-S 

02- e dooi+ 

9-E * 

OI-E • 

tl-fr ' 

OE-5 1 

ue-s isn$ 

EI-E 



xapt// .'J xipu9dd\f 




D 



G 



riufininn UorrlQ 


3-14 


ripipffi Fditnr 

L.' C 1 C L CT J I, vl 1 L U 1 


4-7 


T'evii^lopinc^ SoftwdPG 


10-1 


Diskette Copy 


1-9 


D 1 sol di Speed 


3-38 


00 


3-19 


DOS Coiffliidnds , Editor 


4-11 


nOS Cofnmuni cdti on 


5-23 


DOS Location 


2-3 


DOS Modifications 


2-3 


n DAI.) 
'iKAW 


O- 1 


OrdwifK] Char. Blocks 


7-8 


Drawl nfj 3-0 Imaqes 


8-3 


OkOP 


3-7 


Ou P 


3-7 


Durdtion, Music 


9-3 


F 
I— 




tD! r 


4-2 


Editor, Chardcter 


7-7 


Editor, Imd cje 


8-10 


Editor, Text 


4-4 


E lectri c Duet 


9-5 


ELSE 


3-27 


EMPTY 


6-8 


ERASE 


5-4 


Erase, Editor 


4-8 


Erasinq 3-0 Objects 


8-17 


Error check tng 


3-36 


EXMdOE 


fi-10 


F 




EUL 


6-4 


ront Selection 


7-5 


EQRGET 


3-17 


i-orqettinq Words 


3-17 


Fortd 


1-3 



Get, Editor 4-11 

GETC 5-20 

GETKEY 5-?0 

GETNUM 5-14 

GREEK 6-12 

GR 3-38 

Graphics Colors 6-6 

Graphics Display 3-38 
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GRAFORTH MANUAL ERRATA 



As with any manual as comprehensive as GraFORTH's, a 
few "bugs" managed to creep past our editors. 
Please make note of the following changes: 



PAGE CHANGE 



The last paragraph is inaccurate. The 
bitwise AND of some nonzero numbers 
will produce a zero result. However, 
the word AND is usually used with 
number comparisons that yield a 1 or 
0. If both the top stack value and 
the second stack value are 1 
(representing "true") then the AND of 
the two nunibers will also be 1. If 
either or both numbers are zero, then 
the AND wi 1 1 be zero. 

The BEGIN. ..WHILE. ..REPEAT diagram has 
the =0 and <>0 reversed. The text for 
this section is correct. 

The fifth paragraph should refer to 
Appendix B, not D. 

The word OFF does not immediately 
erase the currently selected object. 
It causes the next DRAW corrunand to 
erase the object, without redrawing 
it. Subsequent cormands to the object 
wll redraw it. The following example 
erases a 3-D object: 



Ready 3 OBJECT OFF DRAW 



Program Control Words 



RUN 

Tlie (SraFORTH word RUN automat i ca 1 l y executes the top word on the 
dictionary. This can be a yreat convenience when loadirif] and 
running prograins from disk. By usinq RUN, you don't have to 
check what the top word on the dictionary is after compilinq a 
file in order to run it. In addition, if the top word has a name 
soi'iethinq like: 

SUPER. ZAPPO.ELECrHO.BLASTFRS.APPLF. VIDRO. GAME, 
uiint) RUN can save a bit of typinq, too.... 



AUTORUN 

Tiie word AllTURDN qoes a step beyond this. ADTORUN removes a 
nui.iber from the stack. If this number is nonzero, then GraFORTH 
will automatically execute the top word on the dictionary every 
time prui)rain control is returned to the GraFORTH system level 
(i.e. whenever you expect to see a "Ready" prompt). DOS errors, 
draFORTII or machine languaqe errors, executing the word ABORT, or 
press inq the Reset key with the AUTORIIN option on will all cause 
trie top dictionary word to be executed. Here is an example to 
jive you a feel for the way AUTORIIN works: 

Ready : TEST PRINT " AUTORIIN IS ON!!! " ; 

We've added this word to the top of the dictionary so that 
AUTORUM will have a very visible effect. 

Ready 1 AUTORUN 
AUTORUN IS ON! ! ! 

Ready 3 5 
AUTORUN IS ON! ! I 
[3] 
[5] 

Ready SWAP 
AUTORUN IS ON! ! ! 
[5] 
[3] 
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Ready ABORT 



(Th( screen clears. ) 

GraFORTH ][ (C) 1981 P. Lutus 

AUTORUN IS ON! ! ! 

Ready 

Fortunately, the AUTORUN option can be turned off by typinq; 

Reaily AUTORUN 

Ready 

If Ihe top dictionary word runs a "closed" program which never 
exits to the system level, the A'JTORUN option effectively makes 
the GraFORTH language itself Inaccessible. Any errors or ABORTs 
simfly restart the program. 

Saving the GraFORTH System 

The GraFORTH language is stored on the system disk as an 
exeiutable binary file with the name "OBJ. FORTH". As mentioned 
in Chapter 3, when the disk is booted, this file is automatically 
loaled and run. 

The GraFORTH word SAVEPRG is used to create GraFORTH binary files 
similar to OBJ. FORTH. SAVEPRG saves the current GraFORTH system, 
including any new words added to the dictionary, as a binary 
fili. Once created, this file can be BRIIN at any time, bringinq 
the modified GraFORTH system back into memory. 

SAVIPRG is a powerful tool. You can save "customized" systems, 
witti your favorite special -purpose words already in the 
dic:ionary when the system is booted. You can also save finished 
applications programs, In such a way that the program 
autjmatlcally starts up when booted. This is ideal for games 
applications, where the obvious presence of a "languaqe" is 
nei;her needed nor desirable. 

To jse SAVEPRG, first compile the words to produce the "finished" 
system you want to save, then type SAVEPRG: 
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Hi 




Red'ly SAVEPRG 
SAVL FILE NAME : 

This proMipr. asks for the filename you want the new system 
saved as. The r.raPORTH systen disk automatically BRUNs the file 
"OliJ FORTH", so if you want this new system to boot 
automatically, you should name your file "OBJ. FORTH" too. Your 
file will then overwrite the suppTfed GraFORTH system. (Make 
sure you're using a copy of the disk and not the orlqinal!) You 
are then prompted: 

AUTORUN (Y/N) : 

This prompt asks whether or not you want the saved system to boot ^ -^-..l^l 

up with the AUTORUN option on. If you answer Yes to this ^3 

question, then the new system will automatically run the top word |=g 

on the dictionary, startinq a profiram in motion. If desired, ^ 4^ 

your program can later turn the AUTORUN option back off, ^ "ft ..^ 

returning access of the GraFORTH language to the user. If you J 

answer the AUTORUN question with No, the new system will display g 

the "Ready" prompt on boot-up, with iimnediate access to the |w ^ ^ --^ 

language. »- p"" 22 

After answering this question, this disk whirs for a bit, saving y 

the new system to disk. Ik. 

Note- As discussed in Chapter 2, a slightly modified version of P 
DOS is used with GraFORTH. Any system saved with SAVEPRG ^ 

requires this version of DOS to be in memory. New systems should ^ ^ ^ 

be saved to a copy of the GraFORTH disk, so that the special OOS iik ^ 
will he present . »^ 

The GraFOKTH system as supplied includes an additional word on 
the top of the dictionary which asks the demonstration prompt on 
boot-up. This word can be found in the disk file "QUERY". The 
system was saved with the AUTORUN option on, so that the demo ^ 
proiupt would come up automatically. When you answer No to the b - ^2 

demo question, the word turns AUTORUN off (freeing the system), w Z5 

then FORGETS itself! This leaves the system in its "usual" ^ 

^■■i ^ 

The GraFORTH system can be saved to disk without the demo prompt | 2 

simply by using SAVEPRG with no additional words on the word L 
library.' (This should only be done to a copy of your disk, in LT . , 

case lightning decides to strike while the system is being 
written to disk.) Boot the disk, answer No to the demo question, 
then type: 



km 



S 
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Ready SAVEPRGi 

SAVE FILE NAWE :OBJ. FORTH 

AUTORUN (Y/N)) :N 

After the dissk stops whirring, turn your Apple off, then on 
again. When the system boots, the demo prompt will be gone. 

You can also put the demo prompt back into the system. Type: 

Ready READ " QUERY " 

This adds the word that asks the demo question to the top of the 
dictionary. Now type: 

Reddy SAVEPRGi 

SAVE FILE NAWE :OBJ. FORTH 

AUTORUN (Y/N)) :Y 

The system wiill be saved with the demo prompt back in. 



Over/ays 



GraFORTH progirairis can automatically load and run other GraFORTH 
programs, andl even delete themselves to free up memory. Program 
segments that; overwrite each other in this way are often called 
"overlays". The GraFORTH demonstration programs use overlays 
extensively. 

To execute am overlay, include a word in the first file that 
reads the overlay. Make the first line in the overlay FORGET the 
words already/ in memory, and the last line in the overlay file 
the word RUN.. To be more specific: 

When you need an overlay, execute a READ <filename>, where 
<filenanie> is; the name of the overlay. This file will now be 
read into meimory, but since the first line of the overlay 
contains a FQIRGET <wordname>, where wordname is the name of the 
GraFORTH wordl you wish to forget back to (inclusive), the 
original file (or portion thereof) will be removed. As reading 
of the overlaay continues, it will now fill memory previously 
occupied by the original file. 
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We une you to examine the demonstration file listings as an 
exaaiple of overlays. Since the FORGE r at the beginning of each 
file does not cause an error if the word being forgotten does not 
exist, the demo files (or any overlay) can also be directly loaded 
and run. 

Moving Memory 



MDVUEM simply moves a block of memory from one location to 

another. MOVMEM removes three numbers from the stack. The form 
tor MOVMFM is: 

<soiirce> <destination> </* of bytes> MOVMEM 

Ihe <sourcp> number is the starting address of the data to be 
moved. The <destination> is the address of where the block is to 
be moved to. <# of bytes> specifies how many bytes are to be 
moved. For example, to move 256 bytes from address 2048 to 
address 2816, enter: 

Ready 204.S 2816 256 MOVMEM 

MOVMEM can be handy for relocating character sets and 3-D images 
in memory, as will be discussed in Chapters 7 and R. 

Retrieving Word Addresses 



Tne wont ' (an apostrophe, also called a "tic") places on the 
stack the address of the word that follows it, and prevents that 
,jord from being executed. Here is an example: 

Ready ' ERASE 
[30749] 

Ihe tic placed the address of the word ERASE on the stack, and 
prevented ERASE from being executed. Note that the tic is a word 
that looks forward down the input line, and retrieves the address 
when it is compiled, not every time it is executed. 

The address returned by "tic" is always greater than the 
hexadecimal address shown with $LIST. This is because the $LIST^^ 
address indicates the beginning of the word definition, and "tic" 
returns the address of the executing portion of the word. See 
Appendix B for more information on the word library structure. 
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Calling Machine Language Routines 



Machine languagje programs in memory can be called directly from 
'■raFURTH with tthe word CALL. CALL removes a number from the 
stack, interprets it as a memory address, then calls the machine 
language roiitime at that address. (The routine should end with 
an RTS (ReTurn from Subroutine) instruction to return to GraFORTH 
properly.) Machine language programs can be loaded from disk 
using the DOS conmiand "BLOAD" into any free area of memory, then 
CALLed from GraFORTH. 

Before a machiine language CALL is made, values can be placed in 
the Apple processor's A, X, Y and P registers using the GraFORTH 
variables ARET,, XREG, YREG and PREG. Before making the machine 
language CALL, simply place the desired values into AREG, XREG, 
YREG and PREG as you would any other variable. When CALL is 
executed, it loads the processor registers with the values from 
these variables before doing the call. (Note the importance of 
loading a proper value into PREG. If improper processor bits are 
set, GraFORTH will not operate!) After the routine has executed, 
the values of ithe registers are loaded back into the variables 
and can he read from GraFORTH, again, just as any other variable. 

Here is a nice example, which uses CALL to read the game paddles. 
The Apple System monitor contains a routine at location -1250 for 
reading the game paddles. It expects to see the number of the 
game paddle (0 to 3) in the processor's X register. It returns a 
number from to 255 (based on the position of the paddle) in the 
Y register. Tliie following word reads the value of a game paddle 
by placing the top stack value in XREG, calling the paddle 
routine, then placing the value of YREG on the stack: 

: READ.PAODLE 
-> XREG 
-1250 CALL 
YREG ; 

(The Apple iiiamuals warn that two consecutive readings of a game 
paddle can produce incorrect results, and suggest a short wait 
loop between readings.) 
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Compilinn Number Tables 



The word "," (comma) causes a nuiaher to be compiled as a byte 
directly into GraFORTH. Small assembly lanquaqe routines can be 
compiled using conimds, or number tables can be qenerated. Here 
is an example of a word that contains a number table of the 
visible high resolution colors. The nuiMbers are stored as 
individual bytes following the word name in memory: 

: COLOR. TABLE 1 , ? . 3 . S , fi , ; 

These numbers correspond to the colors green, violet, white, 
ordnge, and blue. (Colors in GraFORTH will be discussed in 
detail in the next chapter.) Each number can be accessed by 
using the tic to retrieve the address of COLOR. TABLE, then adding 
an offset (0 to 4) to pick out the appropriate number with PEEK. 
^^ote that COLOR. TABLE is jiot an executable word! 

The comma is the only GraFORTH word that assembles directly at 
the byte level, and some precautions are required to use it 
effectively. The comma should only be used within word 
definitions. Also, for internal reasons, the first byte of an 
asseii.bly of code or data may not be greater than 127 (hexadecimal 
$7F), nor can it be equal to 10 ($A). Here are the reasons: K) 
is a special reserved compiler flag, and a number less than 1 2h 
must follow each GraFORTH word name to mark its end. (For more 
information, see Appendix B for technical information on 
GraFORTH's dictionary link structure.) 

Leaving GraFORTH (gently) 

The GraFORTH word "BYE" can be used to enter the Apple ][ system 
monitor. The GraFORTH language begins at hex location $6000. To 
restart GraFORTH from the monitor, type "60nOG". 

Conclusion 



That about wraps up the language features of GraFORTH. From here 
on out we'll be talking about the many types of graphics 
available with GraFORTH. (That ^s what you bought it for, isn't 
it?) The next chapter will cover basic point and line drawing in 
GraFORTH, as well as a discussion of the supplied TURTLEGRAPIIICS . 
We'll get into the various modes, color selections and... 

Well, that's the topic of chapter 6! 
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